Cybele Domain - Features

Real Estate and Construction Intelligence (libs/cybele/*, apps/cybele/*; TODO Phase 58)

Cybele is the Oshun bounded context for built-environment intelligence: land and plots, architectural design, construction delivery, property operations, prefab and modular housing, building materials, real-estate finance, industrial parks, hospitality property, civil infrastructure, and PropTech — scoped to Ghana's built environment. It is an implemented workspace domain with 19 library packages and five application services. Every subsystem shares one foundation — the plot/property/project type system in @cybele/core, geospatial-aware persistence in @cybele/db, and the cross-domain schemas in @contracts/cybele — so a site-analysis score, a construction schedule, and a portfolio valuation all reference the same property identity. Cybele owns built-environment decisions; Brigid owns the industrial automation inside facilities, and Maat owns organization-wide capital and governance rollups.

1. Domain Foundation#

Packages: @cybele/core, @cybele/common, @cybele/db, @cybele/api, @contracts/cybele, @cybele/integration, @cybele/testing

The foundation layer defines the contracts every capability library depends on, so that a plot analyzed for site selection, a building under construction, and a leased unit in a portfolio all reference the same property and plot identity.

• Core primitives — @cybele/core defines twelve branded identifiers (PropertyId, PlotId, BuildingId, UnitId, TitleId, ProjectId, TenantId, LeaseId, ContractorId, MaterialId, InvestorId, FundId) and the plot, property, building, project, unit, lease, material, and financial primitives shared across the domain — together with Zod validators, type guards, and serializers. All monetary values are in Ghana Cedis (GHS) unless a field carries its own currency.

• Shared utilities — @cybele/common holds shared math, date, geo, and ID helpers reused by every capability library.

• Geospatial-aware persistence — @cybele/db owns the Drizzle/PostgreSQL schema and seed data. It uses a PostGIS geometry(Polygon,4326) column type for plot boundaries, PgBouncer connection pooling per service role, and Redis (key prefix cybele) for read-through caching and pub/sub (see §16).

• API library — @cybele/api is the Hono-based API gateway: JWT auth and RBAC, Redis-backed rate limiting, REST routes, GraphQL, gRPC service definitions, WebSocket channels, a Kafka event publisher/consumer, and a hash-chained construction ledger, consumed by the application services.

• Cross-domain contracts — @contracts/cybele defines stable Zod schemas, the CloudEvents 1.0 envelope, and the Kafka topic/event-type registries for inter-domain exchange; @cybele/integration provides the bridge adapters that exchange approved Cybele facts with Brigid, Saraswati, Asase, Freya, and Maat. Consumers never import Cybele internals directly.

• Testing support — @cybele/testing provides fixtures and mocks, including the geospatial, financial, lease, and schedule fixtures that regression tests require (see §19).

2. Core Built-Environment Type System#

@cybele/core defines the canonical objects shared across every subsystem. The types below are the primary aggregates; each drives which capability libraries apply to a given property or project.

2.1 Plot#

A unit of land. Site analysis, design, and construction all attach to a plot.

The Plot type carries titleId, area (m²), boundary (a GeoPolygon with an explicit srid), zoning (a ZoningClassification), topography, soilType, encumbrances, isServiced (roads + power + water + sewer present), tenure (LandTenure), price (GHS), and pricePerSqm (GHS).

The zoning and tenure fields drive permitting and design-code constraints; the boundary drives every spatial calculation in §3.

Geospatial calculations on a plot must preserve its coordinate reference metadata (see §19).

2.2 Property#

A development or asset — the unit of valuation and portfolio management.

• type — the PropertyType enum: Residential, Commercial, Industrial, MixedUse, Land, Hospitality, Healthcare, or Education. The type selects which capability libraries and operating models apply, and which of the four discriminated subtypes (ResidentialProperty, CommercialProperty, IndustrialProperty, MixedUseProperty) extends the base record.

• status — the PropertyStatus enum: Planning, UnderConstruction, Completed, ForSale, ForRent, Occupied, UnderRenovation, or Demolished. A Planning property has no construction telemetry; a Demolished property appears only in historical reporting.

• The property carries currentValue (GHS) and lastValuation (a PropertyValuation record); valuation is updated by §6 portfolio operations and §9 finance.

2.3 ConstructionProject#

A delivery effort that builds or modifies a property.

• status — the ConstructionStatus enum: Bidding, Awarded, Mobilization, InProgress, Substantial (substantial completion), Defects (defects liability period), FinalCompletion. A project also carries an ordered list of ProjectPhase records, each named by the ProjectPhaseType enum — Preconstruction, Foundation, Structure, MEP, Finishing, Handover.

• The project carries contractValue, revisedContractValue (including variations), startDate, plannedCompletionDate, and forecastCompletionDate — all in GHS and date types.

Every schedule and budget change on a project must be auditable; EVM-relevant changes append to the hash-chained construction ledger (see §19 and §16).

3. Site Analysis and GIS#

Package: @cybele/site-analysis · Application: apps/cybele/api

Evaluates plots for development suitability using geospatial data, and ranks candidate sites. The library also covers land-registry checks, including the Ghana Lands Commission integration types (title searches, parcel verification, encumbrance checks).

The site analysis workflow answers the question: "Is this plot suitable for this intended use, and how does it rank among alternatives?" It does this through six analytical layers:

• GIS layers — overlay plots with zoning, infrastructure, hazard, and demographic layers; all spatial work preserves coordinate reference metadata.

• Site suitability scoring — score a plot for an intended use from weighted factors: zoning fit, access, hazard exposure, demographics, and comparable activity.

• Zoning constraints — evaluate the plot's zoning against the intended property type, surfacing permitted use, setbacks, height, and density limits.

• Access analysis — distance and connectivity to roads and to water, power, sewer, and telecom utilities, since lack of utility access is a hard development constraint in Ghana.

• Flood and environmental risk — flag flood exposure and environmental constraints on the plot; this is the same risk surface Gaia weather data enriches (see §17).

• Demographic catchments and foot traffic — population, income, and foot-traffic catchments around the plot, used to rank retail and mixed-use sites.

• Comparable sites and ranking — identify comparable sites and produce a ranked recommendation list, so a developer compares candidates on a common scoring basis rather than judging each in isolation.

4. Architectural Design and BIM#

Package: @cybele/design · Application: apps/cybele/api

Covers architectural design intelligence and Building Information Modeling, from brief through reviewed design. The library provides structured records that connect a design brief to room schedules, BIM model files, code compliance checks, and a formal review workflow.

• Design briefs and space programs — capture the design brief and the space program (required rooms, areas, and adjacencies) as structured records that drive plan generation.

• Room schedules — itemized room schedules with areas and finishes derived from the space program.

• BIM references and model metadata — link BIM model files (in object storage) to the design with structured model metadata, so the model is addressable, not just attached.

• Clash and design-rule checks — detect geometric clashes between building systems and check the design against configured design rules; each issue is tracked to resolution.

• Code constraints — evaluate the design against the plot region's building code (egress, accessibility, fire) so violations surface before permitting.

• Material assumptions — record the material assumptions a design depends on, feeding cost estimation and the §8 materials catalog.

• Plan options and design review — maintain alternative plan options and move drawings and BIM models through their review status (draft, in_review, approved, and onward to issued_for_construction/published), with approval gating the start of construction.

5. Construction Project Management#

Package: @cybele/construction · Application: apps/cybele/projects

Manages construction delivery from procurement through handover, tracking schedule, cost, quality, and risk. Every schedule and budget mutation is auditable via the hash-chained construction ledger.

• Work breakdown structure (WBS) — decompose the project into a hierarchical WBS of deliverables and activities.

• Schedules and milestones — build the construction schedule with milestones and dependencies; a progress update appends a progress_attested event to the hash-chained construction ledger, and a reached milestone emits a cybele.project.milestone_reached CloudEvent.

• RFIs and submittals — track Requests for Information and material/shop- drawing submittals as items with status, owner, and due date.

• Change orders — manage scope, cost, and time changes as change orders that adjust the project budget and schedule with a recorded approval trail.

• Contractor assignments — assign contractors and subcontractors to WBS scope.

• Progress reporting and site diaries — capture daily site diaries and progress against the WBS and schedule, including progress photos (in object storage) and per-WBS-item percent-complete and earned-value figures.

• Risks and incidents — maintain a project risk register and an incident log (including safety incidents).

• Quality checks — record quality inspections against WBS deliverables.

• Completion and handover — drive the handover phase: punch lists, final inspections, and the handover package that transitions the property toward active.

6. Property Portfolio Management#

Package: @cybele/property · Application: apps/cybele/portfolio

Operates income-producing property after handover: tenants, leases, maintenance, and performance. This is the property management layer — it takes over where construction leaves off and runs the asset through its occupied life.

• Assets and units — manage buildings, units, and rooms as the operating inventory of a property portfolio.

• Leases and tenants — full lease lifecycle; an executed lease emits a cybele.lease.executed CloudEvent. Lease and tenant records support privacy, role-based access, and an immutable signoff history (see §19).

• Rent and arrears — track rent due, payments, and arrears per tenant and unit.

• Maintenance — log and schedule property maintenance against units and building systems.

• Occupancy and rent review — track occupancy rates, scheduled rent reviews, and service-charge reconciliation.

• NOI and capex — compute Net Operating Income (rental income less operating expense) and track capital expenditure per asset.

• Valuations and inspections — record periodic valuations and condition inspections; valuations update the property's currentValue (§2.2).

• Performance dashboards — roll occupancy, NOI, arrears, and valuation into property and portfolio performance dashboards.

7. Prefab and Modular Housing#

Package: @cybele/prefab · Application: apps/cybele/factory

Covers modular housing from module design through factory production to on-site installation. The prefab workflow is a key enabler for affordable housing delivery, and it bridges the factory (§8 materials) and construction (§5) worlds by tracking each module from its BOM through to its installed position.

• Module catalogs — maintain a catalog of prefab module designs with dimensions, configurations, and specifications.

• Factory orders — place and track factory orders for modules against a project's requirements.

• Component BOMs — each module carries a bill of materials, feeding the §8 materials catalog and procurement.

• Site readiness — verify the site is ready to receive modules: foundations, access, and utility connections in place.

• Transport constraints — check module dimensions and weight against transport limits, since an oversize module is a hard delivery constraint.

• Installation sequencing and deployment planning — sequence module installation on site and plan the overall deployment.

• Warranty and factory-to-site traceability — record module warranties and maintain traceability from each installed module back to its factory order and production batch.

8. Building Materials#

Package: @cybele/materials · Application: apps/cybele/factory

Owns the building-materials catalog, sourcing, and performance data that design, construction, and prefab depend on. This library is the authoritative source of material specifications; when a design makes a material assumption or a construction project procures stock, it references records here.

• Catalog — a catalog of building materials with specifications and performance data.

• Sourcing and suppliers — supplier records with lead times, pricing, and a supplier-reliability rating.

• Pricing and lead times — track material pricing and lead times over time, feeding cost estimation and construction-cost-movement analysis (§14).

• Alternatives — maintain substitutable-material relationships so a specified material can be swapped under cost or availability pressure.

• Embodied carbon and performance — record embodied carbon and structural/ thermal performance per material, supporting sustainable-design choices.

• Stock and batch QC — track per-warehouse material stock with reorder points and low-stock alerts, and record production/sourced batches with their quality-control test results and pass/fail status.

9. Real-Estate Finance#

Packages: @cybele/finance, @cybele/financials · Application: apps/cybele/portfolio

@cybele/finance owns deal- and project-level real-estate finance; @cybele/financials owns cross-business-unit financial models. Every financial projection retains its input assumptions and a versioned model identifier (see §19), so a valuation or investment memo can be reproduced and audited.

• Mortgages and affordability — model mortgage products and compute borrower affordability against income and rate assumptions.

• Project finance — model the financing of a construction project: debt and equity structure, draw schedules, and interest during construction.

• Investment memos — assemble investment memos for a property or project with the underlying assumptions attached.

• Draw schedules — schedule and track construction-loan drawdowns against project progress.

• Valuation and yield — compute property valuation and investment yield (cap rate, cash-on-cash).

• Sensitivity and scenario modeling — run sensitivity analysis on key inputs (rent, exit yield, cost) and compare financing or development scenarios; each scenario records its own versioned assumption set.

• Lender and investor reporting — produce reporting packs for lenders and investors from the same versioned models.

10. Industrial Parks#

Package: @cybele/industrial-parks · Application: apps/cybele/portfolio

Manages industrial parks and warehouse estates as a distinct property class. Industrial parks introduce multi-tenant utility capacity management — unlike office or residential properties, a park's utility headroom directly limits how much industrial activity it can host.

• Tenant mix — manage the mix of tenants and anchor tenants across a park.

• Utility capacity — track power, water, and other utility capacity against tenant demand, since utility capacity caps how much industrial activity a park can host.

• Warehouse availability — maintain warehouse inventory and availability for leasing.

• Logistics access — record road, rail, and port access as a leasing factor.

• Land banks and infrastructure phasing — track undeveloped land banks and the phased rollout of park infrastructure.

• Lease-up analytics — analyze lease-up rate and absorption across the park.

11. Hospitality Property#

Package: @cybele/hospitality · Application: apps/cybele/portfolio

Operates hospitality property — the building, room inventory, and asset side of hotels. The boundary here is important: Hestia and Annapurna own culinary and restaurant operations; Cybele owns the property envelope (building, rooms, reservations, asset performance).

• Rooms and keys — manage room and key inventory for a hospitality property.

• Bookings — track room bookings and occupancy.

• Revenue management — apply revenue-management logic (rate and availability by demand) to room inventory.

• Facilities and guest operations — manage property facilities and guest-facing operations.

• Capex planning — plan capital expenditure (refurbishment cycles) for the hospitality asset.

• Asset performance — report hospitality asset performance (occupancy, RevPAR-style metrics) into the portfolio dashboards.

12. Civil Infrastructure#

Package: @cybele/infrastructure · Application: apps/cybele/projects

Models civil works and public infrastructure as built-environment assets. Infrastructure projects are different from building projects: they have linear assets (roads, drainage), governmental clients (GHA, GWCL, ECG), and dependencies that upstream other development projects.

• Infrastructure assets — roads, drainage, water, power, sewer, telecom, and public-works assets as managed records.

• Maintenance schedules — maintenance schedules for each infrastructure asset class.

• Service levels — track service levels and condition against targets.

• Project dependencies — model dependencies between infrastructure projects and the developments that rely on them, so a building project's schedule reflects the infrastructure it waits on.

13. PropTech Platform#

Package: @cybele/proptech · Application: apps/cybele/marketplace

The digital real-estate marketplace: listings, agents, inquiries, and digital leasing. This is the buyer- and tenant-facing layer that converts property records and portfolio assets into searchable listings and digital leasing workflows.

• Listings — create and manage property listings for sale or lease, with a listing-quality score.

• Inquiries — capture and route buyer/tenant inquiries against listings.

• Agents and CRM — agent profiles and a CRM for managing leads and client relationships through the deal funnel.

• Tours — schedule and track property tours, physical and virtual.

• Offers — manage offers on a listing through to acceptance.

• Digital leasing — an end-to-end digital leasing workflow that, on completion, produces a lease handled by §6 property operations.

• Marketplace and workflows — the buyer- and tenant-facing marketplace experience over the above.

14. Market Intelligence and Financials#

Packages: @cybele/market-intel, @cybele/financials

Market intelligence provides the analytical layer for pricing and demand decisions; financials rolls up business-unit outputs for governance reporting.

• Comparables — assemble comparable-sale and comparable-lease sets from the market-transaction records, adjusted to a common price-per-square-metre basis (see §16).

• Price and rent indices — compute price and rent indices by submarket and property type.

• Demand forecasting — forecast demand by submarket and property type.

• Pipeline monitoring — monitor the development pipeline (planned and under-construction supply).

• Construction cost movement — track construction-cost movement from the §8 materials pricing history.

• Financial rollups and risk scoring — @cybele/financials rolls business-unit financials and risk scores into the dashboards that Maat consumes for capital and governance.

15. Application Services#

Five services in apps/cybele/* expose Cybele's libraries as operational workflows. The specifications register them as @cybele/app-api, @cybele/app-factory, @cybele/app-marketplace, @cybele/app-portfolio, and @cybele/app-projects. Each service is independently deployable and owns a single operational concern.

• apps/cybele/api — the API gateway app. Exposes gateway-management endpoints: the routing table, client token issue/revoke, per-client rate-limit configuration, API version manifest, audit-log query, downstream service-registry health, an OpenAPI 3.1 document, and webhook subscription and delivery. The REST families themselves (§16) live in the @cybele/api library.

• apps/cybele/portfolio — the portfolio management app: property operations, leases, NOI and occupancy, finance, industrial parks, and hospitality assets.

• apps/cybele/projects — the construction and project-management app: WBS, schedules, RFIs, change orders, progress, quality, and civil infrastructure.

• apps/cybele/marketplace — the PropTech marketplace app: listings, inquiries, agents, tours, offers, and digital leasing.

• apps/cybele/factory — the prefab and building-materials factory app: module catalogs, factory orders, BOMs, and the materials catalog.

16. APIs, Events, and Persistence#

16.1 API Surface#

The @cybele/api gateway is a Hono application (default base path /api/v1) that mounts four REST route groups, alongside a GraphQL endpoint, five gRPC service definitions, and a WebSocket server. The four REST families cover the domain's primary aggregates:

1. /properties — property, building, and unit CRUD plus valuation.
2. /construction — WBS phases, schedule, milestones, inspections, earned value, and progress claims.
3. /leases — lease, tenant, rent-payment, and (nested) maintenance operations.
4. /materials — building-materials catalogue, inventory, production batches, and QC.

Listings, marketplace, and market-intelligence reads are served through the GraphQL API and the apps/cybele/* application services; /listings and /market-intel/prices are public (auth-bypassing) gateway paths.

16.2 Domain Events#

Cybele publishes domain events as CloudEvents 1.0 envelopes over Apache Kafka. Events are named cybele.<aggregate>.<event> and are partitioned by resource ID so all events for a given property, tenant, or project arrive in order.

The canonical registry (CYBELE_EVENT_TYPES in @contracts/cybele) defines 30 event types across six aggregates, each routed to its Kafka topic by aggregate prefix:

buildCybeleEvent(...) constructs the envelope and validateCybeleEvent(...) safe-parses it. The runtime publisher/consumer in @cybele/api use kafkajs over a separate physical-topic registry (cybele-property-events, cybele-construction-events, cybele-lease-events, cybele-finance-events, cybele-iot-events, cybele-notifications, cybele-audit-events) with per-resource partition keys so events for a property, tenant, or project stay ordered. Cybele also exchanges approved facts with Brigid, Saraswati, Asase, Freya, and Maat through the integration bridges (see §18).

16.3 Persistence and Search#

Cybele uses three persistence tiers:

• PostgreSQL / PostGIS — plots, geometries, buildings, units, projects, leases, materials, and market records. The @cybele/db schema (Drizzle ORM) defines a PostGIS geometry(Polygon,4326) column type for plot boundaries and spatial queries.

• Connection pooling — PgBouncer-aware pool profiles per service role (ecommerce, construction, property, analytics, iot, hospitality, finance, admin) so each operational workflow operates with an appropriate connection pool size and pool mode.

• Redis — read-through caching and pub/sub under the cybele key prefix, with per-entity TTLs and cybele:events:* pub/sub channels.

• Object storage — drawings, BIM files, site photos, legal documents, and contracts, in dedicated buckets (CYBELE_DOCUMENT_BUCKET, CYBELE_DRAWINGS_BUCKET, CYBELE_SITE_PHOTOS_BUCKET).

17. Gaia Weather and Climate Integration#

Phase 175 adds Gaia storm, cyclone, precipitation, heat, wind, urban-downscaling, and climate-scenario products as inputs to Cybele. The boundary is clear: Cybele owns the built-environment decisions that result from weather and climate information; Gaia owns the weather and climate ML products and their skill scorecards. Cybele consumes Gaia for:

• Pre-storm asset-hardening alerts
• Construction-site weather risk
• Drainage and flood planning
• Urban heat-island analysis
• Climate adaptation planning
• Schedule risk assessment
• Property-portfolio resilience modeling

18. Cross-Domain Integrations#

All exchange flows through @cybele/integration and @contracts/cybele; consumers never import Cybele internals. Each integration relationship has a clear direction and a clear reason for the boundary.

• Brigid supplies industrial automation, energy, maintenance, and materials/manufacturing intelligence consumed by Cybele factories and facilities. The boundary exists because plant-control logic belongs to Brigid; Cybele only tracks the facility as an asset.

• Neith supplies the real-time visualization renderers (Phase 144, @neith/viz-*): Cybele consumes BIM live-link, walkthrough/VR presentation, and environment/weather visualization for real-estate and construction models. Cybele owns the property/BIM data; Neith owns the renderer.

• Saraswati supplies advanced-technology manufacturing, energy devices, telecom, IoT, and security-systems intelligence that Cybele incorporates into smart-building and IoT-enabled property operations.

• Asase consumes Cybele infrastructure and site-planning data for agricultural facilities. Asase needs to know about road access and service availability for farm sites, but does not own those infrastructure records.

• Freya consumes Cybele retail, manufacturing, and real-estate intelligence for luxury stores, workshops, and factories. Freya models business operations; Cybele models the buildings those operations inhabit.

• Maat consumes Cybele financials, risk, and capital-planning data. Maat performs organization-wide governance rollups; it reads Cybele's financial outputs without needing to understand Cybele's internal models.

Cybele owns land, property, construction, BIM/design, prefab, real-estate finance, and property operations. Brigid owns factory automation and plant control inside facilities; Hestia and Annapurna own culinary and restaurant operations while Cybele owns the restaurant building and property; Freya owns luxury retail and manufacturing business semantics while Cybele owns the stores, factories, and real-estate envelopes.

19. Non-Functional Requirements#

These constraints apply across every subsystem above.

• Geospatial coordinate integrity — every geospatial calculation preserves coordinate reference metadata; a plot boundary carries an explicit srid (default WGS-84, 4326) and is never reprojected or computed against without its CRS, so spatial results stay correct. Property and listing locations are validated to Ghana's bounding box (latitude 4–12°N, longitude −4–2°E).

• Versioned financial-projection assumptions — every financial projection retains its full input assumption set and a versioned model identifier, so a valuation, scenario, or investment memo can be reproduced and audited.

• Auditable construction changes — every construction schedule and budget change is recorded with actor, timestamp, and rationale.

• Lease privacy and immutable signoff — lease and tenant records enforce privacy and role-based access, and carry an immutable signoff history; corrections are append-only and preserve the original record.

• Verification expectations — changes run the affected packages' lint/type/test checks and schema/contract checks. Geospatial, financial, lease, construction-schedule, and compliance changes additionally require explicit fixtures and regression tests.