Cybele Domain — Technical Specifications

Status: IMPLEMENTED. This specification is grounded in the source under libs/cybele/*, apps/cybele/*, and libs/contracts/cybele. Every schema, enum, table, endpoint, event, and state machine documented below traces to real code in those packages; the source file is named at the head of each section. Cybele is the Oshun bounded context for built-environment intelligence — land, property, construction, design/BIM, prefab, building materials, real-estate finance, industrial parks, hospitality property, civil infrastructure, and PropTech — scoped to Ghana's built environment.

This document is the authoritative technical reference for the Cybele domain. It describes every package, type, database table, API endpoint, domain event, and invariant in the implemented codebase. Engineers working on Cybele, or on any domain that integrates with it, should use this document to understand exactly what data Cybele stores, what operations it exposes, and what contracts it publishes.

The specification is organized from inside out: §1 inventories all packages and services; §2 covers the core type system that everything else builds on; §3 describes the PostgreSQL/PostGIS persistence schema; §4 covers the full API surface (REST, GraphQL, gRPC, WebSocket); §5 documents the stable inter-domain contracts; §6 lists all domain events and their Kafka topics; §7 explains the construction on-chain ledger; §8 describes cross-domain integration bridges; §9 lists all environment variables; §10 and §11 state the hard invariants and verification requirements.

1. Package Inventory#

1.1 Library packages (libs/cybele/*)#

Cybele's logic is split into 19 focused library packages rather than one monolithic module. Each package has its own package.json, project.json, and vitest.config.ts and is independently testable. The table below shows the directory name, the NPM package name used in imports, and the primary responsibility of each package.

1.2 Contracts package (libs/contracts/cybele)#

@contracts/cybele — stable cross-domain schemas. Source: src/api-schemas.ts (request/response Zod schemas), src/events.ts (CloudEvents envelope, event type registry, Kafka topic registry, event payload types). Re-exported from src/index.ts.

1.3 Application services (apps/cybele/*)#

Five independently deployable services compose the domain. Each service is responsible for one operational workflow and references the library packages above for its domain logic. The table shows the app directory, the package name, and the HTTP route surface each app owns.

1.4 Workspace facts#

• Nx scope tag: scope:cybele (from each project.json).
• Cybele API port: 4027; database schema name: cybele (from libs/cybele/README.md).
• Phase reference for the build-out: TODO Phase 58 (TODOS/phase-58.md); the Gaia weather/climate integration is Phase 175. The db schema sections carry inline phase subtask anchors such as 58.1.2.6, 58.1.2.9, 58.1.2.11, 58.1.2.12; the API modules carry 58.1.3.x anchors.

2. Core Built-Environment Type System#

Source: libs/cybele/core/src/types.ts, with index re-exports in libs/cybele/core/src/index.ts (types, validators, guards, serializers). The core library is the canonical type system; all monetary values are in Ghana Cedis (GHS) unless a field explicitly carries a currency.

This section documents every type defined in @cybele/core. Subsections 2.1–2.4 cover the foundational types (IDs, enums, spatial, valuation) that everything else builds on. Subsections 2.5–2.13 cover the primary domain objects (plots, properties, construction, contractors, leases, finance, materials, facilities). Subsections 2.14–2.18 cover supplementary types for construction details, tenant management, investment instruments, manufacturing, and the Ghana Lands Commission API integration.

2.1 Branded identifier types#

Cybele uses branded string types for each entity's primary key. This gives compile-time identity safety — you cannot accidentally pass a TenantId where a ProjectId is expected — without any runtime overhead.

types.ts defines twelve branded string ID types, each with a make… factory function (makePropertyId, makePlotId, etc.):

PropertyId, PlotId, BuildingId, UnitId, TitleId, ProjectId, TenantId, LeaseId, ContractorId, MaterialId, InvestorId, FundId.

Each is string & { readonly __brand: '<Name>' }, giving compile-time identity safety without runtime cost.

2.2 Enumerations#

The enumerations below are the state machines and classification vocabularies for the domain. They are string-valued TypeScript enums, so their values appear as readable strings in JSON payloads. Each is also wrapped in a Zod z.nativeEnum(...) schema for runtime validation; those schemas are exported from validators.ts using the naming convention <EnumName>Schema.

types.ts defines the following TypeScript enums (string-valued):

• PropertyStatus — Planning, UnderConstruction, Completed, ForSale, ForRent, Occupied, UnderRenovation, Demolished.
• ConstructionStatus — Bidding, Awarded, Mobilization, InProgress, Substantial (substantial completion), Defects (defects liability period), FinalCompletion.
• LeaseType — FixedTerm, MonthToMonth, RentToOwn, GroundLease, TripleNet, GrossLease.
• PropertyType — Residential, Commercial, Industrial, MixedUse, Land, Hospitality, Healthcare, Education.
• ValuationMethod — Comparative, Income, Cost, DCF.
• ProjectPhaseType — Preconstruction, Foundation, Structure, MEP (mechanical/electrical/plumbing), Finishing, Handover.
• GhanaRegion — all 16 administrative regions of Ghana plus the legacy Brong_Ahafo: Greater_Accra, Ashanti, Western, Central, Eastern, Northern, Upper_East, Upper_West, Volta, Brong_Ahafo, Oti, Bono, Bono_East, Ahafo, Western_North, North_East, Savannah (17 values).
• ZoningClass — Residential_Low, Residential_Medium, Residential_High, Commercial, Industrial_Light, Industrial_Heavy, Mixed_Use, Agricultural, Conservation, Institutional.
• LandTenure — Freehold, Leasehold, Stool_Land, Family_Land, Vested — the customary and statutory tenure categories of Ghanaian land law.

Zod schemas wrapping each enum via z.nativeEnum(...) are exported from validators.ts (PropertyStatusSchema, ConstructionStatusSchema, LeaseTypeSchema, PropertyTypeSchema, ValuationMethodSchema, ProjectPhaseTypeSchema, GhanaRegionSchema, ZoningClassSchema, LandTenureSchema).

2.3 Spatial and address types#

All property and listing locations are expressed in Ghana-specific address and geospatial types. The address type enforces Ghana Post GPS digital-address formatting; the geospatial types always carry an explicit spatial reference ID (srid) so coordinates are never stored without their coordinate system.

• GhanaAddress — region (GhanaRegion), district, locality, streetName, houseNumber, digitalAddressGps, landmark, postalCode. digitalAddressGps holds a Ghana Post GPS digital address; the canonical format is two uppercase letters, hyphen, three digits, hyphen, four digits (e.g. GE-123-4567), enforced by the regex ^[A-Z]{2}-\d{3}-\d{4}$ in GhanaAddressSchema.
• GeoLocation — latitude, longitude, elevation (metres above sea level), srid (Spatial Reference ID; default WGS-84 = 4326).
• GeoPolygon — coordinates (ordered ring of [longitude, latitude] pairs), srid, area (m²), perimeter (m).

GeoLocationSchema constrains latitude to [-90, 90], longitude to [-180, 180], and defaults srid to 4326.

2.4 Valuation and zoning#

Valuation records capture both the computed value and the methodology and assumptions behind it, enabling auditable reproductions of any past valuation. Zoning classifications carry the full set of planning constraints that site analysis and design checks evaluate against.

• PropertyValuation — id, propertyId, method (ValuationMethod), value (GHS), currency, date, valuer (registered valuer/firm), confidence (0–1 coefficient), assumptions (string list), marketComparables (optional MarketComparable[]).
• MarketComparable — address, saleDate, salePrice, area, pricePerSqm, adjustmentFactor, adjustedPrice.
• ZoningClassification — class (ZoningClass), permittedUses, maxDensity (dwelling units/hectare), maxHeight (m), setbackFront, setbackSide, setbackRear (m), farRatio (Floor Area Ratio).

2.5 Land title#

A LandTitle is the formal document that establishes ownership of a plot under Ghanaian land law. Its expiryDate is only populated for leasehold titles; freehold and stool-land titles do not expire. The isDisputed flag triggers additional due-diligence checks in site analysis.

LandTitle — id (TitleId), titleNumber, registrationDate, ownerId, ownerName, plotId (PlotId), encumbrances (string list), area (m² per survey plan), surveyPlanRef, issueAuthority, expiryDate (Date | null — only applicable to leasehold titles), isDisputed.

2.6 Property and property subtypes#

Property is the central domain object — the unit of valuation, portfolio management, and PropTech listing. A base Property record holds fields common to all property types. Four discriminated subtypes extend it, each adding fields relevant to its specific use class. The type literal on each subtype allows TypeScript to narrow to the correct shape. Duck-typed type guards in guards.ts test for subtype by field presence rather than instanceof, so they work across serialization boundaries.

Property (base) — id, type (PropertyType), status (PropertyStatus), address (GhanaAddress), location (GeoLocation), grossArea (m²), netArea (net usable, m²), currentValue (GHS), lastValuation (PropertyValuation), titleId, yearBuilt, description, amenities, images, createdAt, updatedAt.

Four discriminated subtypes extend Property, each pinned by its type literal:

• ResidentialProperty (type: Residential) — bedrooms, bathrooms, floorArea, hasGarden, parkingSpaces, hasPool, furnishing (furnished | semi-furnished | unfurnished), targetMarket (low-income | middle-income | high-income | luxury).
• CommercialProperty (type: Commercial) — officeGrade (A|B|C), floorPlates, columnSpacing, ceilingHeight, loadingDocks, generatorCapacity (kVA), fibreConnected.
• IndustrialProperty (type: Industrial) — warehouseArea, officeArea, loadingDocks, clearHeight (m), craneCapacity (tonnes; 0 if no crane), yardSpace, powerCapacity (kVA), hasRailAccess, hasColdStorage.
• MixedUseProperty (type: MixedUse) — retailPct, officePct, residentialPct, hospitalityPct (each 0–100), totalUnits, retailGLA (gross leasable area for retail, m²), anchorTenant.

guards.ts provides duck-typed (field-presence, not instanceof) type guards for each property subtype and for the specialized facility types.

2.7 Plot, building, unit#

These three types form the physical hierarchy of a developed property: a Plot is a parcel of land, a Building sits on a plot, and Units subdivide a building into individually leasable or saleable spaces. Site analysis works at the Plot level; construction at the Building level; leasing at the Unit level.

• Plot — id (PlotId), titleId, area (m²), boundary (GeoPolygon), zoning (ZoningClassification), topography (flat | gentle_slope | steep_slope | undulating), soilType, encumbrances, isServiced (roads + power + water + sewer present), tenure (LandTenure), price (GHS), pricePerSqm (GHS).
• Building — id (BuildingId), propertyId, name, floors, totalUnits, grossArea, netLeasableArea, structuralSystem (rc_frame | steel_frame | load_bearing | timber), yearBuilt, condition (excellent | good | fair | poor), hasLift, hasBackupPower, hasBorehole.
• Unit — id (UnitId), buildingId, unitNumber, floor, area, type (studio | 1br | 2br | 3br | 4br | penthouse | office | retail | warehouse), status (available | occupied | maintenance | reserved), currentRent (contracted GHS/month), marketRent (estimated GHS/month), tenantId (TenantId | null).

2.8 Construction project, phase, milestone#

A ConstructionProject is broken into ordered ProjectPhase records, each containing Milestone records. This three-level hierarchy (project → phase → milestone) mirrors the standard PMI/FIDIC project breakdown. Milestones that carry a linkedPayment value are payment milestones — when milestone_achieved is recorded on the construction ledger, the linked amount is unlocked for disbursement.

• Milestone — id, name, plannedDate, actualDate (Date | null), isPredecessorComplete, completionCriteria, isCriticalPath, linkedPayment (GHS unlocked by this milestone, or null for a non-payment milestone).
• ProjectPhase — id, name (ProjectPhaseType), status (ConstructionStatus), plannedStart, plannedEnd, actualStart, actualEnd (nullable), percentComplete, cost (GHS), milestones (Milestone[]).
• ConstructionProject — id (ProjectId), name, type (residential | commercial | industrial | infrastructure | mixed_use), status (ConstructionStatus), clientId, propertyId, location (GhanaAddress), contractValue (original, GHS), revisedContractValue (including variations, GHS), startDate, plannedCompletionDate, forecastCompletionDate, percentComplete (0–100), projectManager, mainContractorId (ContractorId), consultants (architect/engineer/QS names), phases (ProjectPhase[]).

2.9 Contractor and subcontractor#

Contractor records represent main contractors; Subcontractor extends Contractor with trade-specific fields. The registrationNumber is the Ghana Revenue Authority or business registration number — a compliance requirement for public procurement in Ghana. The bondingCapacity sets the maximum contract value a contractor can be awarded.

• Contractor — id (ContractorId), companyName, registrationNumber (Ghana Revenue Authority or business registration number), licenseType, licenseExpiry, specializations, rating (1–5, 5 = excellent), bondingCapacity (max GHS), completedProjects, ongoingProjects, contactEmail, contactPhone.
• Subcontractor extends Contractor — adds tradeSpecialisation, crewSize, parentContractorId (ContractorId, optional), dailyCrewRateGhs, ownedEquipment (string list).

2.10 Tenant, lease, rent schedule#

The tenant and lease types model the full rental relationship. A Tenant represents a person or company; a Lease binds a tenant to a specific unit for a period; and RentSchedule is the period-by-period ledger generated from the lease terms. The escalationType field determines how rent increases at each review: a fixed percentage, CPI-linked (with a 4.5% CPI floor applied in the API), or open-market review.

• Tenant — id (TenantId), name, type (individual | corporate), contactEmail, contactPhone, idNumber (national ID, passport, or company registration number), creditScore (300–850), employerName, monthlyIncome (verified GHS), rentalHistory (good | fair | poor), createdAt.
• Lease — id (LeaseId), unitId, tenantId, type (LeaseType), startDate, endDate, rentAmount (GHS/month), rentCurrency (GHS | USD), escalationType (fixed_pct | cpi_linked | market_review), escalationRate (annual %), depositAmount, depositHeld, terms (string list), isActive, renewalOption, breakOption.
• RentSchedule — leaseId, periodStart, periodEnd, dueDate, amount (billed GHS), paid (received GHS), balance (amount − paid), status (current | overdue | paid | partial), daysOverdue, lateFee.

2.11 Finance primitives#

The finance primitives model the instruments used to finance property acquisition and development. MortgageProduct defines the terms of a loan product; AmortizationEntry is one row in a repayment schedule; REITFund is a real-estate investment trust or fund; and DevelopmentProForma is the project-level feasibility model showing cost, revenue, IRR, and equity multiple.

• MortgageProduct — id, name, rateType (fixed | variable | hybrid), nominalRate, effectiveRate (annual %, fees/compounding included), maxLTV (max loan-to-value %), minTenureMonths, maxTenureMonths, minLoanAmount, maxLoanAmount, eligibilityCriteria.
• AmortizationEntry — period, paymentDate, openingBalance, payment, principal, interest, closingBalance.
• REITFund — id (FundId), name, ticker, nav (GHS), navPerUnit, unitsOutstanding, distributionYield (%), totalAssets, totalLiabilities, sectorAllocation (Record<string, number>, values must sum to 100), inceptionDate.
• DevelopmentProForma — projectId, landCost, hardCosts, softCosts, contingency, financingCosts, totalCost, grossRevenue, netRevenue, profit, profitMargin (% of total cost), irr (%), equityMultiple (net revenue / equity invested), paybackPeriod.

2.12 Manufacturing and materials primitives#

These types represent the physical products manufactured or sourced by Cybele's factory and materials operations. PrefabModule is the base unit of modular housing. The concrete, paint, steel, and tile product types carry Ghana Standards Authority certification fields (gsCertified, ghanaStandard) that are required for construction compliance in Ghana.

• PrefabModule — id, designCode, type (studio | 1br | 2br | 3br | classroom | clinic | office), widthM, lengthM, heightM, weightKg, structuralCapacity (kN/m² floor load), connections (array of end | side | top | bottom), productionStatus (design | fabrication | qc | storage | transit | installed), unitCost.
• ConcreteBlock — dimensions (150x225x450mm | 200x225x450mm | 100x225x450mm), strengthNmm2 (compressive, N/mm²), density (kg/m³), hasHollow, gsCertified (Ghana Standards Authority), batchNumber, testDate, testResult (pass | fail).
• PaintProduct — id, formulationCode, name, color, hexCode, finish (matte | eggshell | satin | semi_gloss | gloss), vocGPerL (volatile organic compounds, g/L), coverageM2PerL, dryingTimeHours, shelfLifeMonths.
• SteelProduct — id, profile (I_beam | H_beam | channel | angle | flat_bar | round_bar | hollow_section), gradeS (EN 10025: S275 | S355 | S420), lengthM, weightKgPerM, cross_section_area (cm²), millCertificate.
• BuildingMaterial — id (MaterialId), name, specificationCode, ghanaStandard (optional, Ghana Standards Authority code), unit, unitCostGhs, supplierName, supplierContact, leadTimeDays, minimumOrderQty, certificationBody (optional), certificationNumber (optional), isPrequalified, embodiedCarbonKgCo2 (optional, kg CO₂e per unit), isGreenCertified.

2.13 Specialized facility types#

Beyond the four property subtypes, Cybele tracks additional managed-asset types for specialized built-environment contexts. Each has a propertyId back- reference where applicable, linking it to the base Property record for portfolio management and valuation. Type guards for these are defined in guards.ts.

types.ts defines additional managed-asset records, each with propertyId back-references where applicable:

• IndustrialPark — id, name, location, totalArea (hectares), developedArea, plots, vacantPlots, occupancyRate (%), isFreeZone (GIPC Free Zone status), anchorTenants, utilities (array of power | water | sewer | fibre | gas), masterPlanUrl.
• DataCenter — id, name, tierLevel (Uptime Institute Tier 1–4), powerCapacityMW, pueTarget (Power Usage Effectiveness), rackCount, totalFloorArea, colocationAvailable (m²), connectivity, certifications.
• HospitalityProperty — id, propertyId, name, starRating (1–5), roomCount, serviceType (hotel | serviced_apartment | resort | guesthouse), amenities, revpar (Revenue Per Available Room, GHS), adr (Average Daily Rate, GHS), occupancyRate (%).
• StudentHousing — id, propertyId, university, bedCount, distanceToMainGate (km), amenities, rentPerBedPerAnnum (GHS), occupancyRate (%), mealsIncluded.
• RetailProperty — id, propertyId, gla (gross leasable area, m²), anchorTenant, footTrafficPerDay, parkingRatio (spaces per 100 m² GLA), vacancyRate (%), averageRentPerSqm (GHS/m²/annum).
• ColdStorageFacility — id, propertyId, temperatureZones (TemperatureZone[]), hasBlasFreezer, backupPowerKW, certifications.
• TemperatureZone — name, minTemp, maxTemp, capacityPallets.

2.14 Construction supplementary types#

These types provide the detail behind a ConstructionProject. A ConstructionTask is the atomic WBS unit tracked for earned-value purposes. Blueprint and BIMModel record the drawing and model artefacts for a project. ChangeOrder captures approved scope/cost/time changes with an approval chain. QCInspection records the result of an on-site quality check. SafetyIncident captures OSHA-classified site incidents with follow-up action tracking. WeatherCondition captures daily site weather and its productivity impact — this is the record Gaia data enriches at Phase 175.

• ConstructionTask — the atomic WBS unit. Fields: id, projectId, projectPhaseId, wbsCode (PMI convention, e.g. 1.2.3.4), description, durationDays (working days), predecessorIds (finish-to-start by default), plannedStart, plannedFinish, actualStart (optional), actualFinish (optional), percentComplete (0–100), resources (array of { type: labour | plant | material, description, quantity, unit, unitCostGhs }), plannedValueGhs (BCWS — budgeted cost of work scheduled), isCriticalPath, totalFloat (slack, working days), notes (optional).
• ConstructionEquipment — id, name, category (tower_crane | mobile_crane | excavator | bulldozer | dumper | concrete_mixer | concrete_pump | compactor | generator | scaffolding | formwork | forklift | piling_rig | other), makeModel, capacityDescription, dailyRateGhs, weeklyRateGhs, operatorIncluded, availability (available | on_hire | under_maintenance | decommissioned), currentProjectId (optional), availableFrom (optional), safetyCertExpiry, ownerName, ownerContact.
• Blueprint — architectural/structural/MEP drawing. id, projectId, drawingNumber, revision, title, discipline (architectural | structural | civil | mechanical | electrical | plumbing | fire_protection | landscape), scale, format (A0–A4), fileUrl, fileSizeBytes, fileFormat (pdf | dwg | dxf | svg), issuedForConstructionDate (optional), status (draft | in_review | approved | issued_for_construction | superseded | void), drawnBy, checkedBy (optional), approvedBy (optional), createdAt, updatedAt.
• BIMModel — id, projectId, modelId (unique within the Common Data Environment), lod (Level of Development 100/200/300/350/400/500), discipline (architectural | structural | mep | civil | site | federated), softwareVersion, fileFormat (ifc | rvt | nwd | nwf | nwc | skp | rfa), ifcSchema (optional: IFC2X3 | IFC4 | IFC4X3), fileUrl, fileSizeBytes, coordinateSystem, elementCount (optional), status (draft | in_review | approved | published | archived), authoredBy, createdAt, updatedAt.
• ChangeOrder — id, projectId, voNumber, submittedDate, description, justification, costImpactGhs (positive = addition, negative = omission), scheduleImpactDays (positive = extension), raisedBy (client | contractor | consultant | statutory_authority), approvalChain (ordered array of { approverName, approverRole, status: pending|approved|rejected, decisionDate?, comments? }), status (draft | submitted | under_review | approved | rejected | implemented), approvedCostGhs (optional), approvedScheduleDays (optional), supportingDocs.
• QCInspection — id, projectId, location, category (concrete_pour | rebar_placement | formwork | waterproofing | blockwork | roofing | plastering | tiling | electrical | plumbing | final_completion), inspectionDate, inspector, inspectorOrganisation, checklist (array of { itemCode, description, result: pass|fail|n_a|observation, remarks? }), nonConformanceReports (array of { ncrNumber, description, severity: minor|major|critical, responsibleParty, closureDate?, closureStatus: open|in_progress|closed| accepted_risk }), overallResult (pass | conditional_pass | fail | pending_retest), contractorSignoff (optional), clientSignoff (optional), attachments.
• SafetyIncident — id, projectId, incidentDateTime, severity (near_miss | first_aid | medical_treatment | lost_time | permanent_disability | fatality), oshaClassification (recordable | non_recordable | first_aid_only | fatality), description, location, injuredPartyName (optional), injuredPartyRole (optional), injuredPartyContractor (optional ContractorId), bodyPartAffected (optional), injuryType (optional), lostWorkDays, rootCauses (array of unsafe_act | unsafe_condition | management_system_failure | environmental | equipment_failure), rootCauseDescription, immediateActions, preventiveActions (array of { action, responsiblePerson, dueDate, status: open|in_progress|closed }), requiresRegulatoryNotification, regulatoryNotificationSentDate (optional), reportedBy, investigatedBy (optional), status (reported | under_investigation | closed | regulatory_review).
• WeatherCondition — daily site weather affecting productivity. id, projectId, date, temperatureCelsius ({ min, max, avg }), humidityPct, windSpeedKmh, windDirection, precipitationMm, visibilityKm, weatherType (clear | partly_cloudy | overcast | light_rain | heavy_rain | storm | harmattan | fog), productivityMultiplier (1.0 = no impact, 0.5 = 50% loss), workStoppage, stoppageHours, dataSource (ghana_met | on_site_station | manual_entry), recordedBy (optional).

2.15 Tenant and lease supplementary types#

These types extend the core tenant/lease model with operational detail. MaintenanceRequest is the helpdesk record raised against a unit. ServiceCharge is the annual budget-and-allocation reconciliation for common-area costs shared across tenants. TenantScreening is the pre-tenancy due-diligence record. Eviction tracks the legally required notice-and-proceedings process under the Ghana Rent Act.

• MaintenanceRequest — id, propertyId, unitId (optional), tenantId (optional — null = raised by property manager), category (plumbing | electrical | hvac | structural | appliances | pest_control | cleaning | security | landscaping | other), description, priority (emergency | high | medium | low), reportedAt, targetCompletionDate (SLA target), completedAt (optional), assignedVendorId/assignedVendorName/ assignedTechnicianName (optional), status (open | assigned | in_progress | pending_parts | completed | cancelled | on_hold), estimatedCostGhs/actualCostGhs (optional), costResponsibility (landlord | tenant | shared), satisfactionRating (optional 1–5), photos, notes.
• ServiceCharge — annual service-charge budget and per-tenant allocation. id, propertyId, periodStart, periodEnd, totalGlaM2, budgetItems (array keyed by category ∈ {security, cleaning, electricity_common_areas, water_and_sewage, waste_management, landscaping, lift_maintenance, hvac_maintenance, building_insurance, management_fee, reserve_fund, other} with budgetedGhs and optional actualGhs), totalBudgetGhs, totalActualGhs (optional), allocationBasis (floor_area | equal_share | unit_count), tenantAllocations (per-tenant { tenantId, unitId, tenantGlaM2, allocationPct, chargeGhs, isInvoiced, invoiceDate?, paidDate? }), status (draft | approved | invoiced | reconciled).
• TenantScreening — pre-tenancy assessment. id, prospectiveTenantId, propertyId, unitId (optional), initiatedDate, completedDate (optional), creditCheck ({ provider, score, rating: exceptional|very_good|good|fair|poor, adverseItems, checkedDate }), employmentVerification ({ employerName, employerContact, monthlyGrossIncomeGhs, employmentType: permanent|contract|self_employed| retired|unemployed, yearsEmployed, verified, verificationMethod: payslip|bank_statement|employment_letter|tax_return }), rentalReferences (array of prior-landlord records), identityVerification ({ idType: ghana_card|passport|drivers_license|voters_id, idNumber, verified, verifiedBy? }), rentToIncomeRatio, affordabilityCheck, recommendation (approve | approve_with_conditions | reject | pending), conditions (optional), notes (optional), screenedBy.
• Eviction — id, leaseId, tenantId, propertyId, unitId, grounds (non_payment_of_rent | breach_of_tenancy_terms | property_damage | illegal_activities | owner_occupation | redevelopment | expiry_no_renewal), noticeServedDate, requiredNoticeDays (Ghana Rent Act notice period), vacatePossessionDate, rentArrearsGhs, status (notice_served | negotiation_in_progress | court_proceedings | court_order_obtained | bailiff_instructed | property_vacated | withdrawn), courtProceedings (optional nested record), settlement (optional nested record), actualVacateDate (optional), legalCostsGhs (optional), handledBy, notes.

2.16 Finance and investment supplementary types#

These types cover the full investment lifecycle beyond the basic finance primitives. MortgageApplication is the underwriting record for a loan application, including Bank of Ghana DTI compliance. InvestorAllocation tracks a single investor's stake in a REIT or fund. EquityWaterfall defines the JV distribution waterfall tiers. CapitalCall is the formal drawdown notice to investors. CrowdfundingCampaign tracks a SEC Ghana–registered property crowdfunding offering. DiasporaInvestment models overseas-resident investment with remittance channels, AML checks, and Bank of Ghana approval references.

• MortgageApplication — id, applicantId, applicantName, propertyId (optional), productId, loanAmountGhs, tenureMonths, annualRatePct, grossMonthlyIncomeGhs, monthlyDebtObligationsGhs, debtToIncomeRatio (Bank of Ghana guideline: ≤ 43%), creditScore (optional), employmentType (public_sector | private_sector | self_employed | diaspora), loanToValueRatio, supportingDocuments (array of { type: payslip|bank_statement|tax_return|employment_letter| business_financials, fileUrl, verifiedAt?, verifiedBy? }), status (submitted | document_review | credit_assessment | property_valuation | offer_issued | offer_accepted | legal_processing | approved | rejected | withdrawn), underwritingNotes (optional), approvedAmountGhs/approvedRatePct (optional), offerIssuedDate/offerExpiryDate/decisionDate (optional), rejectionReasons (optional), createdAt, updatedAt.
• InvestorAllocation — investor stake in a REIT/fund. id, investorId, fundId, unitsAllocated, capitalCommittedGhs, capitalCalledGhs, uncalledCapitalGhs, distributionsReceivedGhs, currentNavGhs, totalReturnGhs, irr (optional, decimal), equityMultiple (optional), firstInvestmentDate, investorClass (retail | sophisticated | institutional | diaspora), kycStatus (pending | cleared | expired | flagged), distributionBankAccount (optional { bankName, accountNumber, sortCode, currency: GHS|USD|GBP|EUR }), isActive.
• EquityWaterfall — JV distribution waterfall. id, fundId, name, preferredReturnRate (per-annum decimal), isCumulative, tiers (ordered array of { tierNumber, name, description, lpShare, gpShare, irrHurdle? }), hasCatchUp (GP catch-up provision), returnOfCapitalFirst, waterfallType (american | european), targetIrr, createdAt, updatedAt.
• CapitalCall — id, fundId, callNumber, issuedDate, dueDate, totalAmountCalledGhs, purpose, investmentReferences, investorCalls (per-investor { investorId, allocationId, amountCalledGhs, status: pending|paid|overdue|defaulted|excused, paidDate?, paymentReference? }), status (draft | issued | partially_funded | fully_funded | cancelled), noticeDocUrl (optional), createdBy, createdAt.
• CrowdfundingCampaign — id, propertyId, projectId (optional), title, description, targetAmountGhs, minimumInvestmentGhs, maximumInvestmentGhs (optional regulatory cap), expectedAnnualReturn (decimal), horizonMonths, startDate, closingDate, raisedAmountGhs, investorCount, status (draft | open | overfunded | funded | cancelled | completed), secApprovalReference (optional, SEC Ghana), offeringMemorandumUrl (optional), updates (array of { date, title, body }), createdAt, updatedAt.
• DiasporaInvestment — id, investorId, residenceCountry (ISO 3166-1 alpha-2), sourceCurrency (GBP | USD | EUR | CAD | AUD | JPY | CHF | NOK | SEK), investmentType (direct_property | reit | crowdfunding | off_plan | land_banking), propertyId/ fundId/campaignId (optional), amountSourceCurrency, exchangeRate, amountGhs, remittanceChannel (bank_transfer | mtn_momo | vodafone_cash | western_union | wise | remitly | ghipss), remittanceReference, fundsReceivedDate, fxHedgeReference (optional), amlChecks ({ sourceOfFundsVerified, sourceOfFundsDocument?, pepScreeningClear, sanctionsScreeningClear, checkedDate, checkedBy }), graDeclarationRef (optional, Ghana Revenue Authority), bogApprovalRef (optional, Bank of Ghana — required for remittances

  USD 50,000), status (pending_compliance | active | matured | exited | cancelled), createdAt, updatedAt.

2.17 Manufacturing and materials supplementary types#

These types model the full factory production workflow. A FactoryOrder is a multi-line production order covering any mix of product types. FurnitureProduct and TileProduct extend the materials catalog with product-specific dimensions and certifications. RawMaterialSource tracks the supplier side of procurement. ProductionBatch records a single manufacturing run with yield calculation. QualityTestResult records an individual lab test result referenced to an international standard.

• FactoryOrder — id, customerId, projectId (optional), lineItems (array of { productId, productType: prefab_module| concrete_block|steel|paint|tile|furniture|other, quantity, unit, unitCostGhs, lineValueGhs }), totalValueGhs, requestedDeliveryDate, committedDeliveryDate/actualDeliveryDate (optional), qualityGrade (standard | premium | bespoke), schedule (array of { stage: design_confirmation|material_procurement|fabrication|qc_testing|finishing| dispatch, plannedStart, plannedEnd, actualEnd?, status: pending| in_progress|completed|delayed }), status (draft | confirmed | in_production | qc_hold | ready_for_dispatch | dispatched | delivered | cancelled), deliveryAddress (GhanaAddress), notes (optional), createdAt, updatedAt.
• FurnitureProduct — id, name, designCode, category (bedroom | living_room | dining | office | outdoor | kitchen | storage | bathroom), bom (bill of materials array), dimensions ({ widthMm, depthMm, heightMm }), weightKg, primaryFinish, finishOptions, unitCostGhs, retailPriceGhs, assemblyInstructionsUrl (optional), gsaCertified, leadTimeDays, isActive.
• TileProduct — id, name, productCode, dimensions ({ widthMm, lengthMm, thicknessMm }), material (ceramic | porcelain | granite | marble | slate | travertine | mosaic), finish (polished | matte | satin | textured | rustic | wood_look), colorFamily, slipRating (EN ISO 10545-17: A | B | C | R9–R13), waterAbsorptionPct (EN ISO 10545-3), breakingStrengthN (EN ISO 10545-4), suitableFor (array of floor | wall | outdoor | wet_area | heavy_traffic | commercial), coveragePerBoxM2, piecesPerBox, pricePerM2Ghs, supplierName, countryOfOrigin, gsaCertified, isActive.
• RawMaterialSource — id, material, supplierName, supplierContact, origin, unit, unitCostGhs, priceVolatilityNote (optional), leadTimeDays, minimumOrderQty, qualityGrade, certification (optional), monthlyCapacityUnits, reliabilityScore (0–100, historical delivery performance), isPreferredSupplier, isActive, lastPriceReviewDate.
• ProductionBatch — id, factoryOrderId, productId, productType, batchNumber, plannedQuantity, actualQuantity, rejectedQuantity, yieldPct ((actual − rejected) / planned × 100), startTime, endTime, productionLine, supervisedBy, materialsConsumed (array of { rawMaterialId, materialName, quantityUsed, unit }), qcTestIds, status (in_production | qc_testing | passed | failed | on_hold | scrapped), notes (optional).
• QualityTestResult — id, batchId/materialDeliveryId (optional), testType (compressive_strength | tensile_strength | water_absorption | slump_test | gradation | moisture_content | surface_hardness | impact_resistance | dimensional_check | coating_thickness | chemical_composition | fire_resistance | visual_inspection), specimenId, standardReference (e.g. BS EN 12390-3, ASTM C39, GS ISO 6892-1), measuredValue, unit, minimumRequired/maximumAllowed (optional), result (pass | fail | marginal), laboratoryName, laboratoryAccreditation (optional, e.g. GNBS, UKAS), testDate, testedBy, certificateUrl (optional), notes (optional).

2.18 Ghana Lands Commission (GLC) integration types#

The Ghana Lands Commission is the statutory authority responsible for land administration and title registration in Ghana. Cybele integrates with the GLC API to perform title searches, verify parcel boundaries, check encumbrances, and register deeds. The types below model every request, response, and webhook event in that integration. GlcParcelVerification is the aggregate KYC/AML result that site analysis uses to flag parcels as clean, minor_issues, major_issues, or do_not_proceed.

types.ts defines a dedicated block of interoperability types for the Ghana Lands Commission API (title searches, parcel verification, deed registration, encumbrance checks):

• GlcApiCredentials — apiKey, bearerToken (optional OAuth 2.0 bearer, supersedes apiKey), clientId.
• GlcTitleType — freehold | leasehold | stool_land | family_land | vested_land | concession.
• GlcStoolLandRegion — GREATER_ACCRA | ASHANTI | EASTERN | CENTRAL | WESTERN | VOLTA | BRONG_AHAFO | NORTHERN | UPPER_EAST | UPPER_WEST (Office of the Administrator of Stool Lands regions).
• GlcSearchStatus — pending | in_review | completed | expired (result older than 3 months) | disputed (court caveat/injunction) | not_found.
• GlcTitleSearchRequest — titleNumber, region, purpose (purchase_due_diligence | mortgage_security | litigation_support | internal_audit), requestingOrganisation, parcelId (optional).
• GlcEncumbrance — type (mortgage | caveat | caution | restriction | court_order | lease_notation), holder, principalAmountGhs (optional), lodgedDate, expiryDate (optional), instrumentNumber, notes (optional).
• GlcParcelBoundary — parcelId, officialAreaSqm, boundary (GeoJSON Polygon, WGS84/EPSG:4326), centroidGng (optional Ghana National Grid EPSG:25000 { easting, northing }), lastSurveyDate, surveyPlanRef.
• GlcOwnershipRecord — ownerName, ownerId (masked Ghana Card/TIN), registrationDate, disposedDate (string | null), acquisitionMethod (purchase | gift | inheritance | court_order | government_grant), instrumentNumber.
• GlcTitleSearchResult — searchReference, titleNumber, status, titleType, firstRegistrationDate, lastUpdatedDate, resultDate, expiryDate (3-month validity), currentOwners, ownershipHistory, encumbrances, parcel (optional), hasPendingApplications, isGeoreferenced, certificatePdfUrl (optional), digitalSignature (optional JWS compact serialisation).
• GlcDeedRegistrationRequest — titleNumber, instrumentType (transfer | mortgage | lease | discharge | caveat | power_of_attorney), grantor/grantee ({ name, id }), considerationGhs (optional), executionDate, documentBase64, documentHash (SHA-256), witnesses, solicitor (optional).
• GlcDeedRegistrationResponse — applicationNumber, status (submitted | under_review | queued_for_execution | registered | rejected), estimatedCompletionDate (optional), stampDutyGhs/ processingFeeGhs (optional), rejectionReason (optional), acknowledgementPdfUrl (optional).
• GlcWebhookEvent — eventType (title_updated | encumbrance_lodged | encumbrance_discharged | ownership_transferred), titleNumber, eventTimestamp, transactionReference, signature (HMAC-SHA256), summary.
• GlcParcelVerification — aggregate KYC/AML result. parcelId, titleNumber, boundaryVerified, areaDeltaSqm (positive = seller overstated), hasUnresolvedDisputes, hasUnregisteredEncumbrances, riskRating (clean | minor_issues | major_issues | do_not_proceed), issues (array of { code, severity: info|warning|critical, description }).

3. Persistence Schema#

Source: libs/cybele/db/src/schema.ts (Drizzle ORM, pg-core). The schema targets PostgreSQL with PostGIS (a custom geometry(Polygon,4326) column type, cybelePostgisPolygon, is defined). All tables are exported in a single schema object alongside their relations. Decimal precision constants: area numeric(10,2) / plot area numeric(12,2), money numeric(14,2).

The database schema name is cybele. The section is organized by functional cluster: §3.1 lists all PostgreSQL enum types (which appear in column definitions below); §3.2–3.10 cover each table group; §3.11 describes the Drizzle relation definitions; §3.12–3.13 document connection pooling and Redis configuration.

3.1 PostgreSQL enum types (pgEnum)#

Cybele defines database-native enum types so that column values are validated by PostgreSQL itself, not only by application code. The enum names follow the cybele_ prefix convention. The following enum types are defined in schema.ts; values that are non-obvious are noted inline:

cybele_prop_status, cybele_prop_type, cybele_construction_status, cybele_lease_type, cybele_escalation_type, cybele_ghana_region (17 values), cybele_zoning_class, cybele_land_tenure, cybele_maintenance_priority (critical, high, medium, low), cybele_inspection_category (11 values), cybele_mat_category (Cement, Steel, Timber, Aggregates, Blocks, Roofing, Electrical, Plumbing, Finishing, Prefab, Other), cybele_mat_qc_status (Pending, Passed, Failed, OnHold, Quarantined), cybele_reit_fund_type (Equity, Mortgage, Hybrid, Infrastructure), cybele_reit_fund_status (Fundraising, Investing, Operating, Divesting, Closed, Wound_Up), cybele_room_type (Standard, Deluxe, Suite, Executive, Presidential, Studio, Serviced_Apartment, Dormitory), cybele_booking_status (Inquiry, Provisional, Confirmed, Checked_In, Checked_Out, No_Show, Cancelled), cybele_infra_type (14 values: Trunk_Road, Feeder_Road, Urban_Road, Bridge, Culvert, Drainage, Water_Supply, Sewerage, Power_Transmission, Telecoms, Airport, Port, Railway, Dam), cybele_infra_project_status (Feasibility, Design, Procurement, Construction, Commissioning, Operational, Decommissioned), cybele_road_surface (Bitumen_Surface_Dressing, Asphalt_Concrete, Concrete, Gravel, Laterite, Earth).

3.2 Property, plot, building, unit tables#

The property cluster stores the core built-environment hierarchy. The base cybele_properties table is extended by type-specific tables via 1:1 FK relationships, mirroring the TypeScript discriminated union in §2.6. Spatial data lives in cybele_plots as both a GeoJSON JSONB column and a PostGIS geometry(Polygon,4326) column (the latter is indexed for spatial queries). Buildings subdivide into floors (cybele_building_floors), floor plans (cybele_floor_plans), units, and common areas.

• cybele_properties — base property record. id (uuid PK, defaultRandom), property_type, status, address_json (jsonb, not null), location_json (jsonb), gross_area_sqm, net_area_sqm, current_value_ghs, title_id, year_built, description, amenities (text[]), images (text[]), created_at, updated_at.
• cybele_residential_properties — 1:1 extension keyed by property_id FK → cybele_properties. bedrooms, bathrooms, floor_area_sqm, has_garden, parking_spaces, has_pool, furnishing, target_market.
• cybele_commercial_properties — 1:1 extension. office_grade, floor_plates_sqm, column_spacing_m, ceiling_height_m, loading_docks, generator_capacity_kva, fibre_connected.
• cybele_plots — id (uuid PK), title_id, area_sqm, boundary_geojson (jsonb), boundary_geometry (PostGIS geometry(Polygon,4326)), zoning, topography, soil_type, is_serviced, tenure, price_ghs, price_per_sqm.
• cybele_buildings — id (uuid PK), property_id FK, name, floors, total_units, gross_area_sqm, net_leasable_area_sqm, structural_system, year_built, condition, has_lift, has_backup_power, has_borehole.
• cybele_building_floors — id, building_id FK, level_number, level_name, usage_type, gross_area_sqm, net_area_sqm, elevation_m, spatial_path (hierarchical path string), sort_order.
• cybele_floor_plans — id, building_id FK, floor_id FK (→ cybele_building_floors), plan_type, version, drawing_ref, storage_uri, file_format, scale, source_system, geometry_json (jsonb), is_current, issued_at, superseded_at.
• cybele_units — id, building_id FK, floor_id FK, unit_number, floor, area_sqm, unit_type, status, current_rent_ghs, market_rent_ghs, tenant_id, spatial_path, centroid_json, boundary_json.
• cybele_common_areas — id, building_id FK, floor_id FK, name, area_type, area_sqm, access_level, maintained_by, spatial_path, boundary_json.
• cybele_land_titles — id, title_number (unique, not null), registration_date, owner_id, owner_name, plot_id FK (→ cybele_plots), encumbrances (text[]), area_sqm, survey_plan_ref, issue_authority, expiry_date, is_disputed.

3.3 Construction tables#

The construction cluster stores projects, their WBS breakdown, milestones, and quality inspection records. The cybele_wbs_items table is self-referencing (parent_item_id) to represent the WBS tree. Earned-value fields (budgeted_cost_ghs, earned_value_ghs, actual_cost_ghs) are stored at the WBS item level for detailed EVM reporting.

• cybele_construction_projects — id, name, project_type, status (cybele_construction_status), client_id, property_id FK, location_json (jsonb, not null), contract_value_ghs (not null), revised_contract_value_ghs, start_date, planned_completion_date (not null), forecast_completion_date, percent_complete (real, default 0), project_manager (not null), main_contractor_id, consultants (text[]), created_at, updated_at.
• cybele_project_phases — id, project_id FK, phase_name, phase_status, planned_start, planned_end, actual_start, actual_end, percent_complete, cost_ghs.
• cybele_wbs_items — work breakdown structure tasks. id, project_id FK, phase_id FK, parent_item_id (self-reference for the WBS tree), wbs_code, name, description, item_type, status, responsible_org, planned_start/planned_end/actual_start/ actual_end, duration_days, budgeted_cost_ghs, actual_cost_ghs, earned_value_ghs, percent_complete (real, default 0), predecessors_json (jsonb), metadata_json (jsonb), created_at, updated_at.
• cybele_milestones — id, phase_id FK, name, planned_date, actual_date, is_critical_path, linked_payment_ghs.
• cybele_quality_inspections — id, project_id FK, category (cybele_inspection_category), location, inspection_date, inspector, results_json (jsonb, not null), overall_status, ncrs (text[]).

3.4 Tenant, lease, rent, maintenance tables#

The tenant cluster stores the full rental relationship. cybele_leases links a tenant to a unit; cybele_rent_schedules is the period-by-period billing ledger derived from a lease; cybele_rent_payments records each received payment with its mobile-money or bank channel. cybele_maintenance_tickets is the service request log, with SLA target dates computed from priority at creation time (critical = 1 day, high = 3 days, medium = 7 days).

• cybele_tenants — id, tenant_type, name, contact_email, contact_phone (not null), id_type, id_number, address, employer_name, monthly_income_ghs, credit_score, rental_history, created_at, is_active (default true).
• cybele_leases — id, unit_id FK, tenant_id FK, lease_type (cybele_lease_type), start_date, end_date, rent_amount_ghs (not null), rent_currency (default GHS), escalation_type (cybele_escalation_type), escalation_rate (real), deposit_amount_ghs (not null), deposit_held (not null), renewal_notice_days (default 90), terms (text[]), is_active (default true), created_at, terminated_at.
• cybele_rent_schedules — id, lease_id FK, tenant_id FK, unit_id FK, period_number, period_start, period_end, due_date, amount_ghs, paid_ghs, balance_ghs, status, days_overdue (default 0), late_fee_ghs (default 0), generated_at, last_payment_at.
• cybele_rent_payments — id, lease_id FK, schedule_id FK, tenant_id, amount_ghs (not null), channel, reference_number (not null), payment_date, status, note, confirmed_at.
• cybele_maintenance_tickets — id, property_id, unit_id, tenant_id, category, description (not null), priority (cybele_maintenance_priority), reported_at, target_completion_date (not null), assigned_vendor_id, status, actual_cost_ghs, estimated_cost_ghs, completed_at, notes.

3.5 Market and PropTech tables#

The market cluster stores the public-facing PropTech data: active property listings, comparable-sale transactions used for valuation, competing developments tracked for market intelligence, and mortgage applications. cybele_market_transactions records are the comparable sales that the finance modules adjust and index.

• cybele_property_listings — id, title, description, property_type, transaction_type, price_ghs (not null), currency (default GHS), bedrooms, bathrooms, area_sqm (not null), district, region, latitude, longitude, amenities (text[]), images (text[]), agent_id (not null), status, published_at, view_count (default 0), inquiry_count (default 0), quality_score (default 0).
• cybele_market_transactions — comparable sale records. id, transaction_date, property_type, location, district, region, area_sqm, transaction_price_ghs, price_per_sqm, bedrooms, is_verified (default false).
• cybele_competitor_developments — id (uuid PK, defaultRandom), name, type, status, lat/lon (numeric(9,6)), region, scale, year_completed, source, created_at/updated_at (timestamptz).
• cybele_mortgage_applications — id, applicant_id, property_id, product_id, loan_amount_ghs, tenure_months, annual_rate_pct (real), gross_monthly_income_ghs, monthly_debt_obligations_ghs, credit_score, employment_type, status, approved_amount_ghs, approved_at, created_at.

3.6 Industrial-park and prefab tables#

Industrial-park plots subdivide a park into individually leasable land parcels (distinct from the building Unit concept). Prefab production is tracked in three linked tables: a module design catalog, individual production orders, and per-module factory order items that trace through each production station. On-site assembly tasks are linked back to the factory order item for full traceability from module design to installed position.

• cybele_industrial_park_plots — id, zone_id, area_m2, status, frontage_m, depth_m, monthly_lease_rate_ghs_per_sqm, tenant_id, tenant_name, allocated_power_kw, allocated_water_m3_per_day.
• cybele_prefab_module_designs — id, design_code (unique), module_type, version, description, external_dimensions_json (jsonb, not null), internal_dimensions_json (jsonb), finished_weight_kg, structural_capacity_kn_m2, stackable_floors, production_days (not null), unit_cost_ghs (not null), bom_json (jsonb), drawing_refs (text[]), assembly_instructions_url, is_active, created_at, updated_at.
• cybele_prefab_orders — id, design_id FK, module_type, quantity, design_code, customer_name, delivery_date, priority, status, unit_cost_ghs, start_date, completed_date.
• cybele_prefab_factory_order_items — per-module production line items. id, order_id FK, design_id FK, module_serial, sequence_number, station, production_status, started_at, completed_at, qc_status, dispatch_ready_at.
• cybele_prefab_assembly_tasks — on-site assembly steps. id, order_id FK, order_item_id FK, assembly_step, task_name, status, planned_start/planned_end/actual_start/actual_end, crew_code, dependency_json (jsonb), percent_complete (real, default 0), inspection_status, notes.

3.7 Materials tables (phase anchor 58.1.2.6)#

The materials cluster stores the catalog, warehouse stock levels, production batches, and QC test results. The cybele_material_inventory table is per-warehouse, so a single material item can have stock tracked across multiple locations simultaneously. cybele_material_batches enables batch traceability; cybele_material_qc_records stores individual test results against a batch using international test standards (e.g. BS EN 12390, ASTM C39).

• cybele_material_items — master catalogue. id, sku (unique), name, category (cybele_mat_category), unit_of_measure, specification, ghana_standard (GSA code), supplier_id, unit_cost_ghs (not null), lead_time_days (default 7), minimum_order_qty (default 1), created_at, updated_at.
• cybele_material_inventory — per-warehouse stock. id, material_id FK, location_code, quantity_on_hand, quantity_reserved, quantity_on_order, reorder_point, valuation_ghs, last_count_date, updated_at.
• cybele_material_batches — manufactured/sourced batch records for traceability. id, material_id FK, batch_number (unique), manufacture_date, expiry_date, quantity_produced, production_line, raw_material_cost_ghs, labor_cost_ghs, overhead_cost_ghs, qc_status (cybele_mat_qc_status, default Pending), certification_ref, notes, created_at.
• cybele_material_qc_records — id, batch_id FK, tested_by, test_date, test_type, test_standard (e.g. BS EN 12390, ASTM C39), result, unit, min_acceptable, max_acceptable, status (cybele_mat_qc_status), lab_reference, report_url, created_at.

3.8 REIT / fund tables (phase anchor 58.1.2.9)#

The REIT cluster stores real-estate investment trust structures. A cybele_reit_funds record is the top-level fund entity, referencing its SEC Ghana registration. cybele_reit_portfolio_items links fund records to underlying property assets. cybele_reit_nav_snapshots records periodic NAV computations (NAV = gross asset value minus total liabilities). Investor records track KYC status and distributions received.

• cybele_reit_funds — id, name, ticker (unique), fund_type (cybele_reit_fund_type), status (cybele_reit_fund_status, default Fundraising), target_size_ghs, raised_ghs (default 0), inception_date, maturity_date, distribution_frequency (default quarterly), target_distribution_yield_pct, management_fee_pct (default 1.5), performance_fee_pct (default 20), custodian, trustee, sec_registration_ref (SEC Ghana), prospectus_url, created_at, updated_at.
• cybele_reit_portfolio_items — id, fund_id FK, property_id FK, acquisition_date, acquisition_cost_ghs, current_valuation_ghs, ownership_pct (default 100), annual_noi_ghs, last_valuation_date, valuation_method, encumbered_ghs (mortgage debt on the asset, default 0).
• cybele_reit_nav_snapshots — id, fund_id FK, snapshot_date, gross_asset_value_ghs, total_liabilities_ghs, nav_ghs (GAV − liabilities), units_outstanding, nav_per_unit_ghs (NAV / units), dividend_paid_ghs (default 0), management_fee_ghs, computed_by, notes, created_at.
• cybele_reit_investors — id, fund_id FK, investor_name, investor_type, ghana_card_or_tin, units_held, subscription_price_ghs, subscription_date, total_invested_ghs, total_distributions_ghs (default 0), bank_account_ref, kyc_status (default Pending), created_at.

3.9 Hospitality tables (phase anchor 58.1.2.11)#

The hospitality cluster extends the base property record with hotel-specific operational data. A cybele_hospitality_properties record (1:1 with a cybele_properties record) carries PMS system references and channel manager details. Room inventory and dynamic rate calendars are stored separately so rate overrides can be managed without touching the room record. Booking confirmation numbers are unique across the table for guest reference.

• cybele_hospitality_properties — id, property_id FK (unique), star_rating, brand_name, total_rooms (not null), meeting_room_count (default 0), restaurant_seats (default 0), pool_available, gym_available, spa_available, pms_system, channel_manager_ref, check_in_time (default 14:00), check_out_time (default 12:00).
• cybele_room_inventory — id, hospitality_property_id FK, room_number, floor, room_type (cybele_room_type), max_occupancy (default 2), size_sqm, bed_configuration, connecting_room, is_accessible, is_active, amenities_json (jsonb), base_rate_ghs.
• cybele_rate_calendar — daily/seasonal rate overrides per room type. id, hospitality_property_id FK, room_type, valid_from, valid_to, rate_name (rack, corporate, group, advance_purchase, …), rate_ghs_per_night, breakfast_included, min_night_stay (default 1), advance_purchase_days, is_active, created_at.
• cybele_bookings — id, confirmation_no (unique), hospitality_property_id FK, room_id FK, guest_name, guest_email, guest_phone, guest_nationality, status (cybele_booking_status, default Inquiry), check_in_date, check_out_date, adults (default 1), children (default 0), rate_ghs_per_night, total_nights, total_amount_ghs, deposit_paid_ghs (default 0), balance_due_ghs, channel_source, special_requests, booked_at, updated_at.

3.10 Civil infrastructure tables (phase anchor 58.1.2.12)#

Civil infrastructure projects differ from building projects in that they have linear assets (roads measured in chainages), governmental clients (client_name e.g. GHA, GWCL, ECG), environmental impact permit references, and pavement condition indices. Road segments store AASHTO structural numbers and California Bearing Ratio values — the engineering parameters that determine pavement design life. Maintenance logs track post-maintenance PCI scores to measure intervention effectiveness.

• cybele_civil_infra_projects — id, name, project_code (unique), infra_type (cybele_infra_type), status (cybele_infra_project_status, default Feasibility), region (cybele_ghana_region), district, contractor_name, consultant_name, client_name (not null — e.g. GHA, GWCL, ECG), contract_value_ghs, funding_source (GoG, World Bank, AfDB, …), commencement_date, original_completion_date (not null), revised_completion_date, actual_completion_date, length_km, area_ha, design_life_years, environ_impact_ref (EPA Ghana permit reference), created_at, updated_at.
• cybele_road_segments — id, project_id FK, segment_code, description, start_chainage/end_chainage (km), length_km, carriagewidth_m, lanes (default 2), surface_type (cybele_road_surface), design_speed (km/h), structural_number (AASHTO SN), cbr (subgrade California Bearing Ratio %), adt (Average Daily Traffic, vehicles/day), pci_score (Pavement Condition Index 0–100), last_survey_date, construction_status (default Not_Started), completion_pct (default 0), created_at, updated_at.
• cybele_infra_maintenance_logs — id, project_id FK, segment_id FK, maintenance_type (routine, periodic, rehabilitation, emergency), priority (cybele_maintenance_priority), description, scheduled_date, completed_date, contractor, estimated_cost_ghs, actual_cost_ghs, funding_ref, defects_rectified (text[]), post_maintenance_pci (real), supervising_engineer, notes, created_at.

3.11 Relations#

Drizzle relations declarations in schema.ts enable type-safe query composition across the table groups above. The following relation chains are defined — each represents a join path that application queries can traverse:

schema.ts declares Drizzle relations joining the major aggregates: property → residential/commercial details, buildings, construction projects; building → floors, floor plans, units, common areas; construction project → phases, WBS items, inspections; phase → WBS items, milestones; tenant → leases, rent schedules, rent payments; lease → unit, tenant, rent schedules, payments; plot ↔ land titles; material item → inventory, batches; batch → QC records; prefab module design → orders, factory order items; prefab order → factory order items, assembly tasks; REIT fund → portfolio items, NAV snapshots, investors; hospitality property → rooms, rate calendar, bookings; civil infra project → road segments, maintenance logs.

3.12 Connection pooling (phase anchor 58.1.2.21)#

Different service roles have different connection requirements. A construction update that holds a transaction open needs a session pool mode; a read-only analytics query can use transaction mode. Cybele defines per-role pool profiles so each service opens only the connections it needs without starving others.

Source: libs/cybele/db/src/connection.ts. PgBouncer-aware pool profiles are defined per ServiceRole: ecommerce, construction, property, analytics, iot, hospitality, finance, admin. Each PoolProfile carries an application-side max connection count, a PgBouncer pgbMaxPool server-connection size, and a PgBouncer pool mode (transaction, session, or statement). The pooling design assumes a PostgreSQL max_connections of 200 in production.

3.13 Redis caching and pub/sub#

Redis serves two roles in Cybele: caching frequently-read records to reduce database load, and pub/sub for real-time notifications between service instances. All keys are namespaced under cybele: and TTLs are calibrated to the read/write frequency of each entity (listings change more often than price indices, so their TTLs are shorter).

Source: libs/cybele/db/src/redis-config.ts. Cybele uses Redis (key prefix cybele) for read-through caching and pub/sub.

• CybeleRedisKeys — keyed accessors: property, propertyList, listing, searchResults, priceIndex, constructionProject, leaseByUnit, tenantProfile, agentSession, marketSnapshot, maintenanceQueue.
• CybeleRedisTTL (seconds) — PROPERTY 600, LISTING 300, SEARCH 120, PRICE_INDEX 3600, MARKET_SNAPSHOT 1800, AGENT_SESSION 86400, TENANT_PROFILE 900, CONSTRUCTION_PROJECT 300.
• CybelePubSubChannels — PROPERTY_UPDATE, LISTING_PUBLISHED, RENT_RECEIVED, MAINTENANCE_RAISED, PROJECT_MILESTONE (all under the cybele:events:* namespace).

4. API Surface#

The API layer is built on Hono and assembled in @cybele/api. Subsections 4.1–4.5 cover the core REST routes, auth, and rate limiting. Subsections 4.6–4.10 cover the auxiliary protocols (GraphQL, gRPC, WebSocket). Section 4.11 covers the deployable API gateway app's own management endpoints. Section 4.12 describes the four non-gateway application services' domain layers.

4.1 Gateway (@cybele/api)#

Source: libs/cybele/api/src/gateway.ts. createGateway(config) builds a Hono application mounted at the configurable basePath (default /api/v1). GatewayConfig accepts basePath, corsOrigins, timeoutMs (default 30000), enableAuth (default true), enableRateLimit (default true), enableMetrics (default true), jwtSecret, and redisUrl (default redis://localhost:6379).

Middleware pipeline, in order: secureHeaders → cors → requestId → structured JSON logging → OpenTelemetry tracing → Prometheus request metrics → request timeout → per-IP sliding-window rate limiter → JWT auth → (dev only) Hono request logger. Public paths bypassing JWT auth: <basePath>/health, <basePath>/metrics, <basePath>/listings, <basePath>/market-intel/prices. The gateway mounts four REST route groups (/properties, /construction, /leases, /materials) plus /health and /metrics. A 404 fallback returns code CYBELE_404; the global error handler returns code CYBELE_500 with the request ID.

CYBELE_SERVICE_REGISTRY is the service dispatch table mapping a route prefix to a downstream service descriptor (name, routePrefix, healthPath): property (/properties), construction (/construction), lease (/leases), tenant (/tenants), materials (/materials), listings (/listings, service cybele-proptech), finance (/finance), market-intel (/market-intel).

4.2 Property REST routes (routes/properties.ts, anchor 58.1.3.2)#

The property routes provide CRUD over the property hierarchy plus valuation. Each route is guarded by a requirePermission(...) middleware that checks the caller's role against the RBAC matrix (§4.6). The route layer uses an injectable PropertyRepository; in production, DrizzlePropertyRepository issues real SQL through @cybele/db.

All routes live under /api/v1/properties:

CreatePropertySchema validates propertyType (one of eight PropertyType literals), status (one of seven non-Demolished literals), address (Ghana address with the XX-NNN-NNNN digital-address regex), location (latitude constrained to 4–12°N, longitude to −4–2°E — Ghana's bounding box), grossAreaSqm (positive), netAreaSqm, currentValueGHS, titleId, yearBuilt (1900 … current year + 5), description (10–5000 chars), amenities, images (URLs). The list query supports type, status, region, district, minArea/maxArea, minValue/maxValue, page (≥1), limit (1–100, default 20), sort (createdAt | currentValueGHS | grossAreaSqm), order (asc | desc). The route layer uses an injectable PropertyRepository; setPropertyRepository(...) swaps the default InMemoryPropertyRepository for a DrizzlePropertyRepository so handlers issue real SQL through @cybele/db. The valuation estimator applies a purposeOfValuation-dependent factor (0.97 for mortgage) and a valuationType factor (0.82 for forced_sale), falling back to a region-based price/m² (Greater Accra 5900, Ashanti 4500, else 3800 GHS/m²).

4.3 Construction REST routes (routes/construction.ts, anchor 58.1.3.3)#

The construction routes drive a project from creation through completion. Three mutations write signed events to the hash-chained construction ledger (§7): POST / records budget_committed; PUT /:id records progress_attested; POST /:id/progress-claim records payment_settled. The earned-value endpoint derives its metrics from that ledger rather than from ephemeral state.

All routes live under /api/v1/construction:

CreateProjectSchema validates name (3–200 chars), projectType (residential | commercial | industrial | infrastructure | mixed_use), propertyId (optional UUID), contractValueGHS (positive), startDate/plannedCompletionDate (datetimes; completion must be after start), projectManager, clientId, mainContractorId (optional), consultants (optional), location ({ region, district, latitude?, longitude? }). QualityInspectionSchema constrains category to the 11 inspection categories and overallStatus to pass | conditional_pass | fail | pending_retest. ProgressClaimSchema carries claimNumber, periodFrom/periodTo, workDoneGHS, materialsOnSiteGHS, retentionPct (0–10, default 5), variationOrders, submittedBy; the handler computes gross claim, retention deduction, approved-variation total, and net-certified amount.

4.4 Lease and tenant REST routes (routes/leases.ts, anchor 58.1.3.4)#

The lease routes handle the full tenancy lifecycle — creation, renewal, termination, payment recording, and arrears calculation. Maintenance tickets are nested under leases because they are raised in the context of a tenancy. Tenant routes are also grouped here. All routes live under /api/v1/leases.

Lease routes: GET / (list), POST / (create — lease:write), GET /:id (with arrears), PUT /:id, POST /:id/renew, POST /:id/terminate, GET /:id/payments, POST /:id/payments, GET /:id/arrears, POST /:id/escalate.

Tenant routes: GET /tenants, POST /tenants, GET /tenants/:id (with payment score), PUT /tenants/:id, DELETE /tenants/:id (deactivate), GET /tenants/:id/leases, GET /tenants/:id/score.

Maintenance routes (nested): POST /:id/maintenance (maintenance:write), GET /:id/maintenance (maintenance:read).

CreateTenantSchema validates tenantType (individual | company | government | ngo), contactPhone (10–15 chars), idType (ghana_card | passport | drivers_license | tin | company_reg), creditScore (300–850). LeaseShapeSchema validates unitId/tenantId (UUIDs), leaseType (six LeaseType literals), escalationType (fixed_pct | cpi_linked | market_review), escalationRate (0–50%), renewalNoticeDays (30–365, default 90), rentCurrency (GHS | USD | EUR | GBP); CreateLeaseSchema refines that endDate is after startDate. RecordPaymentSchema constrains channel to mtn_momo | vodafone_cash | airteltigo | bank_transfer | cheque | cash. TerminateLeaseSchema.reason is one of mutual_agreement | breach_by_tenant | breach_by_landlord | property_sold | property_redevelopment | non_payment | tenant_relocation. MaintenanceTicketSchema.priority is critical | high | medium | low; the handler sets targetCompletionDate to 1/3/7 days out depending on priority. Arrears are computed from months elapsed since the last payment versus payments made; escalation applies a CPI floor of 4.5% for cpi_linked leases and a +5% premium for market_review leases.

4.5 Materials REST routes (routes/materials.ts, anchor 58.1.3.5)#

The materials routes manage the catalog, warehouse inventory, and production QC lifecycle. Material SKUs and batch numbers are unique across their tables; the route returns HTTP 409 on a duplicate. The low-stock alert endpoint and QC summary dashboard aggregate across all materials, so they use a separate /inventory/alerts and /batches/qc-summary path rather than nesting under a material ID.

All routes live under /api/v1/materials:

CreateMaterialSchema requires sku (uppercase alphanumeric, regex ^[A-Z0-9-]+$), category (one of the 11 cybele_mat_category values), unitOfMeasure, unitCostGHS (positive), leadTimeDays (0–365, default 7). QCTestSchema.testType is one of 15 test types; assessQCStatus returns Pending when neither minAcceptable nor maxAcceptable is set, Failed when the result is outside the band, otherwise Passed. A batch's qcStatus is Failed if any test failed, Pending if there are no tests or any test is pending, otherwise Passed. Batch cost is split into raw material / labour / overhead with per-component percentages.

4.6 Authentication and RBAC (auth.ts, anchor 58.1.3.9)#

Cybele uses HS256 JWTs verified in-process. The token carries the caller's role, and the ROLE_PERMISSIONS matrix maps each role to its allowed operations. The requireOwnership guard adds a resource-level check on top of role-level permission for owner-role callers. Below are the full token payload shape, role list, permission list, and role-to-permission matrix.

Cybele uses HS256 JWTs verified in-process (verifyJwt) — header alg must be HS256, the signature is checked with timingSafeEqual, the token must not be expired, and the issuer must be cybele-auth.

• CybeleTokenPayload — sub (user/service account ID), role, ownerId/tenantId/agentId (role-specific scoping), exp, iat, iss.
• CybeleRole — owner, tenant, agent, contractor, developer, finance, admin.
• Permission — property:read/write/delete, lease:read/write, maintenance:read/write, construction:read/write, materials:read/write, finance:read/write, listing:read/write, market-intel:read, admin:*.
• ROLE_PERMISSIONS — explicit grant matrix. owner: property read/write, lease read/write, maintenance read/write, listing read/write, finance read, market-intel read. tenant: property read, lease read, maintenance read/write, listing read. agent: property read, listing read/write, market-intel read, maintenance read. contractor: construction read/write, materials read, property read. developer: property read/write, construction read/write, materials read/write, finance read, market-intel read. finance: property read, finance read/write, market-intel read, construction read. admin: admin:* (grants everything).
• requirePermission(permission) throws 401 if unauthenticated, 403 if the role lacks the permission. requireOwnership(getResourceOwnerId) ensures an owner-role caller can only touch resources where ownerId matches; admin bypasses, other roles are not subject to the check.

4.7 Rate limiting (rate-limit.ts, anchor 58.1.3.10)#

Rate limits are tiered by role, with per-endpoint overrides for routes that are known to be expensive. The sliding-window counter uses Redis sorted sets and a 60-second window.

Sliding-window counter backed by Redis sorted sets. Per-role tiers in RATE_LIMIT_TIERS (maxRequests per 60000 ms): anonymous 60, owner 200, tenant 100, agent 500, contractor 200, developer 300, finance 200, admin 2000. ENDPOINT_RATE_LIMITS adds stricter per-endpoint overrides: GET /api/v1/properties 30/min (expensive PostGIS queries), POST /api/v1/listings 10/min (anti-spam), POST /api/v1/finance 20/min (CPU-bound), and a market-intel export override.

4.8 GraphQL API (graphql/schema.ts, anchor 58.1.3.6)#

The GraphQL API complements the REST surface for queries that span multiple aggregates or need flexible spatial filtering. It is particularly used by the marketplace app for listing search and by the portfolio app for cross-asset financial views.

@cybele/api exports a schema-first GraphQL SDL (typeDefs) and a typed resolver map (resolvers, with ResolverContext and Resolvers types). The SDL declares DateTime and JSON scalars; enums mirror the core enums (PropertyType, PropertyStatus, ConstructionStatus, GhanaRegion, MaterialCategory, TransactionType). Key object types: Property, Listing, Transaction (comparable sale/rental), ConstructionProject, Lease, Tenant, MarketPrice/PriceIndex, plus SpatialFilter input supporting radius (centre + km), polygon (GeoJSON coordinates), district, and region filtering.

Query fields: property, properties (with PropertyFilter + pagination), listing, listings, listingsNearby (lat/lon/radiusKm, distance-ordered), marketTransactions, priceIndex, constructionProject, constructionProjects, tenant, tenants, lease, leases, reitFund, reitFunds, material, materials. Mutation fields include createProperty, updateProperty, createListing, updateListingStatus, createLease, renewLease, terminateLease.

4.9 gRPC service definitions (grpc/definitions.ts, anchor 58.1.3.8)#

gRPC services expose Cybele's core operations as strongly-typed RPC interfaces, suitable for service-to-service calls from other Oshun domains. Streaming RPCs (SearchPropertiesNearby, StreamProjectUpdates, StreamPaymentEvents, SendBulk) enable real-time data push without polling.

Five Protocol Buffers 3 service definitions are embedded as TypeScript string constants and registered in CYBELE_GRPC_SERVICES with default ports:

NotificationService defines NotificationChannel (SMS, WHATSAPP, EMAIL, PUSH, IN_APP) and NotificationPriority (NORMAL, HIGH, CRITICAL).

4.10 WebSocket server (websocket/server.ts, anchor 58.1.3.7)#

The WebSocket server delivers real-time push updates to connected clients. Clients subscribe to typed channels (e.g. project:proj-123) after authenticating with a JWT on the upgrade request. Channel subscription is authorized by the same role-based rules as the REST API.

CybeleWebSocketServer delivers real-time updates over ws. Clients authenticate by passing a JWT in a ?token= query parameter (or Authorization: Bearer header) on the upgrade. Channels follow the format <type>:<id> with types project, lease, property, building, agent, iot.

• WsMessageType — progress_update, milestone_reached, inspection_submitted, variation_order, rent_received, rent_arrears_alert, maintenance_raised, maintenance_resolved, listing_enquiry, price_alert, iot_sensor_reading, iot_sensor_alarm, building_occupancy, ping, pong, subscribe, unsubscribe, error.
• WsMessage — type, channel, data, timestamp, correlationId (optional).
• canSubscribeToChannel(channel, userRole, userId) authorizes subscriptions per channel type: project channels are open to contractor/developer/owner/admin; lease to tenant/owner/admin; property to owner/agent/contractor/developer/admin; building and iot to owner/developer/admin; agent to agent/admin. admin may subscribe to anything. broadcast(channel, message) fans a message out to every subscribed client.

4.11 Application gateway (apps/cybele/api, anchor 58.17.5.x)#

The deployed API gateway app (distinct from the @cybele/api library) adds operational management endpoints: routing configuration, client token lifecycle, rate-limit policy, audit log access, downstream service health, OpenAPI documentation, and webhook delivery. These management endpoints are not exposed by the library itself — they belong to the deployed application boundary.

Source: apps/cybele/api/src/routes/gateway.ts. The deployable API app exposes gateway-management endpoints under its own router:

• GET /routes — routing table (/api/v1/projects/**, /portfolio/**, /marketplace/**, /factory/**).
• POST /auth/tokens, POST /auth/tokens/:clientId/revoke, GET /auth/tokens/:clientId — client token issue/revoke/inspect.
• GET /rate-limits, POST /rate-limits, POST /rate-limits/check — per-client rate-limit configuration and check.
• GET /versions — API version manifest (current v1, URL-path versioning).
• GET /logs, POST /logs — audit-log query and append (AuditLogEntry with clientId, method, path, statusCode, correlationId, durationMs; the store keeps the last 10000 entries).
• GET /health/services, POST /health/services/:serviceId/ping, POST /services — service-registry health aggregation and registration (built-in services: cybele-projects, cybele-portfolio, cybele-marketplace, cybele-factory).
• GET /openapi.json — OpenAPI 3.1.0 document for the projects, portfolio, marketplace, factory, and gateway APIs.
• GET /webhooks, POST /webhooks, PATCH /webhooks/:webhookId, DELETE /webhooks/:webhookId, POST /webhooks/:webhookId/deliver, GET /webhooks/:webhookId/deliveries — webhook subscription and delivery management. A WebhookSubscription carries targetUrl, an events array, an HMAC signing secret, isActive, and a failureCount; WebhookDelivery records event, payload, status (pending | success | failed | retrying), and attempts.

4.12 Application service domains#

The four non-gateway apps each define a small in-memory domain layer (their own state machine types and in-memory stores) that sits above the library packages. This means each app can be deployed and tested independently without requiring a live database, while the library packages provide the domain logic. The key state machines per service are listed below:

• apps/cybele/projects — ProjectStage lifecycle (feasibility → planning → design → construction → commissioning → handover → complete); endpoints for dashboard, schedule/Gantt, daily reports, RFIs, change orders, QC, safety, earned value, documents, notifications.
• apps/cybele/portfolio — Property (status active | under_development | vacant | disposed), Lease (status active | notice_given | expired | terminated), RentRecord; endpoints for portfolio summary, property detail, tenants, rent collection, maintenance, financials, valuation, lease calendar.
• apps/cybele/marketplace — Listing (status active | under_offer | sold | let | withdrawn), Agent; endpoints for listings, search, recommendations, agents, inquiries/leads, viewings, comparison, market analytics, favourites.
• apps/cybele/factory — ProductionStation pipeline (scheduled → framing → rebar → concrete_pour → curing → MEP_rough → insulation → board_up → MEP_finish → finishing → QC_inspection → dispatch_ready), ProductionOrder (status draft | confirmed | in_production | qc_hold | ready | dispatched | cancelled); endpoints for production orders, station scheduling, QC, material inventory, logistics, KPI dashboard, module configuration.

5. Contract Schemas#

Source: libs/contracts/cybele/src/api-schemas.ts. These Zod schemas are the stable inter-domain contract surface and are independent of the runtime route schemas in @cybele/api.

The distinction matters: the runtime route schemas in @cybele/api can evolve with the service implementation; the contract schemas in @contracts/cybele are the external promises Cybele makes to other domains. Other domains import only from @contracts/cybele — never from @cybele/api or @cybele/core directly. Each schema pair below defines what is acceptable for creating a record (request) and what is guaranteed to be present in a response.

• CreatePropertyRequestSchema / PropertyResponseSchema — type (six literals; note this contract omits Healthcare/Education), status (six literals), address (with the ^[A-Z]{2}-\d{3}-\d{4}$ digital-address regex), location (latitude 4–12, longitude −4–2), grossArea (positive), description (20–2000 chars), amenities, images (URLs). The response extends the request with id, currentValue, createdAt, updatedAt.
• CreateProjectRequestSchema / ProjectResponseSchema — name (3–200 chars), type (residential | commercial | industrial | infrastructure | mixed_use), propertyId (optional), contractValueGHS (positive), startDate/plannedCompletionDate, projectManager, clientId. The response adds id, status (draft | active | on_hold | completed | cancelled), progressPct (0–100), actualCostGHS, createdAt, updatedAt.
• CreateLeaseRequestSchema / LeaseResponseSchema — unitId, tenantId, type (six LeaseType literals), startDate/endDate (refined: end after start), rentAmountGHS (positive), depositAmountGHS, escalationType, escalationRate (0–50%). The response adds id, status (draft | active | expired | terminated | renewed), nextRentDue, totalArrearsGHS, createdAt, updatedAt.
• MortgageApplicationSchema / MortgageDecisionSchema — applicantId, propertyId, loanAmountGHS (positive), tenureMonths (12–360), productId, employmentType (salaried | self_employed | business_owner), grossMonthlyIncomeGHS, monthlyDebtObligationsGHS, creditScore (300–850). The decision carries status (approved | conditional | declined | pending_docs), approvedAmountGHS, interestRatePct, monthlyInstallmentGHS, conditions, declinedReasons, debtToIncomeRatio, decidedAt.
• CreateListingRequestSchema / ListingResponseSchema — title (10–200 chars), description (50–5000 chars), propertyType (house | apartment | office | land | warehouse | retail | hotel), transactionType (sale | rent | lease), priceGHS, bedrooms/bathrooms (0–20), areaSqm, district, region, amenities, images (≥1 required). The response adds id, status (active | pending | sold | withdrawn | expired), viewCount, enquiryCount, publishedAt, createdAt, updatedAt.
• PropertyValuationRequestSchema / PropertyValuationResponseSchema — propertyId, valuationType (market_value | forced_sale | insurance_replacement | rental_value), purposeOfValuation (mortgage | sale | taxation | insurance | accounting), valuerId, inspectionDate. The response carries estimatedValueGHS, confidenceLevel (high | medium | low), comparableTransactions, valuationDate, validUntil.

6. Domain Events#

Cybele publishes domain events as CloudEvents 1.0 envelopes over Apache Kafka. There are two event-definition surfaces and one runtime publisher.

Understanding the two surfaces is important: the contract registry in @contracts/cybele defines logical event types and the CloudEvents envelope schema — this is the stable external contract. The runtime registry in @cybele/api/src/kafka.ts defines physical Kafka topic names, partition counts, and the publisher/consumer implementation. Other domains subscribe to the logical contract events; the physical topic names are an implementation detail.

6.1 Contract event registry (@contracts/cybele)#

Source: libs/contracts/cybele/src/events.ts.

• CybeleEventSchema — the CloudEvents 1.0 envelope (Zod): specversion (literal 1.0), id, source, type, subject, time (datetime), datacontenttype (literal application/json), data (unknown), correlationId (optional), businessUnit.
• CYBELE_EVENT_TYPES — the canonical event-type registry, all named cybele.<aggregate>.<event>:
  • Property: cybele.property.created, cybele.property.updated, cybele.property.listed, cybele.property.sold, cybele.property.valuation_done.
  • Construction: cybele.project.created, cybele.project.milestone_reached, cybele.project.completed, cybele.project.quality_inspection_failed, cybele.project.safety_incident, cybele.project.variation_order, cybele.project.progress_claim.
  • Lease: cybele.lease.executed, cybele.lease.renewed, cybele.lease.terminated, cybele.lease.rent_received, cybele.lease.arrears_warning, cybele.lease.rent_review.
  • Finance: cybele.finance.mortgage_approved, cybele.finance.mortgage_declined, cybele.finance.capital_call, cybele.finance.distribution, cybele.finance.payment_default.
  • Prefab: cybele.prefab.order_created, cybele.prefab.module_completed, cybele.prefab.module_delivered, cybele.prefab.module_installed.
  • Market: cybele.market.listing_created, cybele.market.listing_expired, cybele.market.offer_received, cybele.market.offer_accepted.
• CYBELE_KAFKA_TOPICS (contracts) — cybele.properties, cybele.construction, cybele.leases, cybele.finance, cybele.prefab, cybele.market. resolveKafkaTopic(eventType) routes a CloudEvents type to its topic by aggregate prefix.
• Event payload types — PropertyCreatedData, ProjectMilestoneData, SafetyIncidentData, LeaseExecutedData, RentPaymentData, RentArrearsData, MortgageApprovedData, CapitalCallData, DistributionData, PrefabModuleData, ListingCreatedData. For example, ProjectMilestoneData carries projectId, milestoneName, completionPct, plannedDate, actualDate, varianceDays; RentArrearsData carries escalationLevel (warning | notice | legal).
• buildCybeleEvent(type, subject, data, businessUnit, correlationId?) constructs an envelope; validateCybeleEvent(event) safe-parses it against CybeleEventSchema.

6.2 Runtime Kafka integration (@cybele/api)#

Source: libs/cybele/api/src/kafka.ts (anchor 58.1.3.18). The runtime publisher/consumer use kafkajs and a separate physical-topic registry:

• CYBELE_KAFKA_TOPICS (runtime) — cybele-property-events, cybele-construction-events, cybele-lease-events, cybele-finance-events, cybele-iot-events, cybele-notifications, cybele-audit-events.
• TOPIC_PARTITION_COUNTS — recommended partition counts: cybele-property-events 12, cybele-construction-events 6, cybele-lease-events 6, cybele-finance-events 3, cybele-iot-events 24 (high-volume), cybele-notifications 3, cybele-audit-events 6. Partition key is propertyId/tenantId/projectId so every event for a resource lands on the same partition, preserving per-resource ordering.
• CybeleEventPublisher — connect, disconnect, publish, publishBatch; messages are GZIP-compressed and carry ce-* CloudEvents headers.
• CybeleEventConsumer — registers per-event-type handlers via on(), consumes, and routes failures to a dead-letter topic or handler (KafkaDeadLetterRecord, createDeadLetterRecord).
• createCybeleEvent(...) builds the CloudEvents envelope; createDefaultPublisher() reads brokers from KAFKA_BROKERS.

The runtime publisher also exports Prometheus counters kafkaMessagesPublished and kafkaMessagesConsumed.

7. Construction On-Chain Ledger#

Source: libs/cybele/api/src/routes/construction-ledger.ts. The Earned Value Management endpoint (GET /construction/:id/earned-value) does not trust ephemeral route state — it derives its inputs from an authoritative, hash-chained, signed ledger.

The ledger exists because construction finance depends on tamper-evident records: lenders and investors need to know that a budget commitment, a progress attestation, or a payment settlement has not been retroactively altered. The hash-chain design (each event commits to the previous event's hash) means any modification to a past event changes every subsequent hash and is detected by verifyChain. The default InMemoryConstructionLedger is suitable for testing; production deployments swap in an EVM/JSON-RPC backend via setConstructionLedger(...).

7.1 Ledger events#

Each ledger event corresponds to one EVM-relevant construction mutation. The four event kinds capture the four moments that matter to project finance: committing a budget, attesting progress, settling a payment, and achieving a milestone. The hash and signature fields make each event self-authenticating.

ConstructionEventKind — budget_committed, progress_attested, payment_settled, milestone_achieved. Each event extends OnChainEventBase: kind, projectId, recordedAt, transactionHash (0x + SHA-256 of canonical event data), blockNumber (monotonically increasing), prevHash (previous on-chain hash for this project, forming a per-project Merkle-style chain — 0x000…0 at genesis), signature (ECDSA secp256k1 over the canonical data), validatorAddress.

• BudgetCommittedEvent — budgetAtCompletionGHS, startDate, plannedCompletionDate, contractRef.
• ProgressAttestedEvent — percentComplete, attestedBy, attestedAt.
• PaymentSettledEvent — claimId, amountGHS, paidAt, payerAddress, payeeAddress.
• MilestoneAchievedEvent — phaseId (optional), milestoneId, achievedAt, linkedPaymentGHS (optional).

ConfirmedConstructionEvent projects an event with a confirmations count (currentBlock − blockNumber + 1).

7.2 Ledger contract and backend#

ConstructionLedger defines recordBudget, recordProgress, recordPayment, recordMilestone, getProjectEvents, getCurrentBlock, verifyChain (validates the per-project hash chain and every signature, returning the failing index and reason on a break), and reset. The default InMemoryConstructionLedger keeps the chain in process memory with a deterministic signing secret and a genesis block (12_000_000). setConstructionLedger(...) swaps in a real EVM/JSON-RPC backend. The route layer wires ledger writes to the four EVM-relevant mutations (create-project → budget_committed, update-progress → progress_attested, progress-claim → payment_settled, phase-complete → milestone_achieved).

7.3 EVM derivation#

Earned Value Management requires four input scalars: Budget at Completion (BAC), Planned Value (PV), Earned Value (EV), and Actual Cost (AC). Cybele derives these from the authoritative ledger — not from the database state — so the EVM computation is reproducible and auditable at any point in time.

deriveEvmInputs(...) aggregates confirmed ledger events into the four EVM scalars: budgetAtCompletion (most recent confirmed budget_committed; falls back to the in-memory contract value, marked source: 'in_memory_fallback'), percentComplete (latest confirmed progress_attested, else derived from achieved-milestone count), actualCostToDate (sum of confirmed payment_settled.amountGHS with paidAt ≤ asOf), plannedValueToDate (linear S-curve of BAC × elapsed-fraction). computeEarnedValue(...) then produces the standard EVM metrics: earned value, schedule variance, cost variance, SPI, CPI, TCPI, EAC (estimate at completion), ETC, VAC (variance at completion), and scheduleStatus/costStatus classifications.

8. Cross-Domain Integration#

Source: libs/cybele/integration/src/* (brigid-bridges, saraswati-bridges, asase-bridges, freya-bridges, maat-bridges), re-exported from index.ts. All exchange flows through @cybele/integration and @contracts/cybele; consumers never import Cybele internals.

Each bridge is a dedicated adapter module responsible for translating between Cybele's internal types and the stable contract types used by the peer domain. This means a change to Cybele's internal schema only requires updating the bridge, not the consuming domain. Cross-domain endpoint URLs are environment-driven (see §9) so the same bridge code works in every deployment environment.

• Brigid — supplies industrial automation, energy, maintenance, and materials/manufacturing intelligence for Cybele factories and facilities.
• Saraswati — supplies advanced-technology manufacturing, energy devices, telecom, IoT, and security-systems intelligence.
• Asase — consumes Cybele infrastructure and site-planning data for agricultural facilities.
• Freya — consumes Cybele retail, manufacturing, and real-estate intelligence for luxury stores, workshops, and factories.
• Maat — consumes Cybele financials, risk, and capital-planning data.

Cross-domain endpoint URLs are environment-driven (see §9): BRIGID_API_URL, SARASWATI_API_URL, ASASE_API_URL, FREYA_API_URL, MAAT_API_URL.

Phase 175 additionally adds Gaia storm, cyclone, precipitation, heat, wind, urban-downscaling, and climate-scenario products as inputs to Cybele (pre-storm asset-hardening alerts, construction-site weather risk, drainage and flood planning, urban heat-island analysis, climate adaptation, schedule risk, and portfolio resilience). The WeatherCondition core type (§2.14) is the on-site weather record those products enrich.

9. Configuration and Environment#

Source: libs/cybele/README.md and the gateway/Kafka modules.

All Cybele services read configuration from environment variables at startup. The table below lists every variable, its purpose, and the default value where one is defined in code. The local development stack is started with docker compose -f docker/docker-compose.cybele.yml up -d.

The local infrastructure stack is started with docker compose -f docker/docker-compose.cybele.yml up -d.

10. Invariants and Hard Requirements#

These constraints are enforced in the code cited above and apply across the entire domain. They are not optional — violating any of them would produce incorrect financial results, invalid geospatial data, or compromised audit trails. Engineers adding new routes, schemas, or migrations must verify that these invariants are preserved.

• Ghana geographic bounds — property and listing location inputs are validated to Ghana's bounding box: latitude 4–12°N, longitude −4–2°E (CreatePropertySchema, CreatePropertyRequestSchema).
• Digital-address format — digitalAddressGps must match ^[A-Z]{2}-\d{3}-\d{4}$ (Ghana Post GPS), enforced in core validators and route schemas.
• Coordinate reference integrity — GeoLocation/GeoPolygon carry an explicit srid (default 4326); the PostGIS boundary_geometry column is declared geometry(Polygon,4326). Spatial data is never stored or computed without its CRS.
• Lease date ordering — endDate must be strictly after startDate (CreateLeaseRequestSchema and CreateLeaseSchema refinements); construction plannedCompletionDate must be after startDate, and a phase's plannedEnd after its plannedStart.
• Escalation bounds — lease escalationRate is constrained to 0–50% per annum.
• Mortgage bounds — tenureMonths 12–360, creditScore 300–850; underwriting tracks debtToIncomeRatio against the Bank of Ghana ≤ 43% guideline.
• Auditable construction changes — every EVM-relevant change appends a signed, hash-chained event to the construction ledger; verifyChain detects any tampering by reporting the first failing event index and reason.
• REIT NAV identity — nav_ghs is gross asset value minus total liabilities; nav_per_unit_ghs is NAV divided by units outstanding; REITFund.sectorAllocation percentages must sum to 100.
• Material SKU and batch uniqueness — material SKUs and batch numbers are unique; the routes return HTTP 409 on a duplicate, and sku/batch identifiers are uppercase-alphanumeric.
• Per-resource event ordering — Kafka events are partitioned by resource ID so all events for a property/tenant/project preserve ordering within their partition.
• Soft deletion — property deletion is a soft delete (deletedAt is set); records are retained for historical reporting.

11. Verification Expectations#

Changes run the affected packages' lint, type-check, and test gates (pnpm nx test|lint|build <project>, or, when Nx is unavailable, npx vitest run and npx tsc --noEmit from the package directory).

The @cybele/testing package provides the fixtures for domain correctness tests — not just shape tests. Geospatial, financial, lease, construction-schedule, and compliance changes are in a higher risk tier and require explicit regression fixtures that would fail on incorrect computations. Geospatial, financial, lease, construction-schedule, and compliance changes additionally require explicit fixtures and regression tests; @cybele/testing provides the fixtures and mocks those tests build on. Each library ships co-located test files (*.test.ts, *.spec.ts, integration tests) covering domain correctness — including the construction ledger's hash-chain and signature verification, the EVM derivation, the GLC integration types, and the materials QC pass/fail logic.

12. Grounding Statement#

Every package name in §1 is taken from the corresponding package.json. Every type, enum, and field in §2 is defined in libs/cybele/core/src/types.ts (validators/guards in validators.ts/guards.ts). Every table, column, and PostgreSQL enum in §3 is defined in libs/cybele/db/src/schema.ts; pooling and Redis facts come from connection.ts and redis-config.ts. Every endpoint, middleware, and RBAC rule in §4 is defined in libs/cybele/api/src/gateway.ts, src/auth.ts, src/rate-limit.ts, the four src/routes/*.ts files, src/graphql/schema.ts, src/grpc/definitions.ts, src/websocket/server.ts, and apps/cybele/api/src/routes/gateway.ts; the app-service domains come from each apps/cybele/*/src/routes/*.ts. Every contract schema in §5 is defined in libs/contracts/cybele/src/api-schemas.ts. Every event, topic, and payload type in §6 is defined in libs/contracts/cybele/src/events.ts and libs/cybele/api/src/kafka.ts. The ledger in §7 is defined in libs/cybele/api/src/routes/construction-ledger.ts. The integration bridges in §8 are defined under libs/cybele/integration/src/. The environment variables in §9 come from libs/cybele/README.md. No schema, enum, endpoint, event, table, or state machine in this document was invented; anything not present in the cited code is not described here.