cybele library

The Cybele API gateway and service mesh (libs/cybele/api/src). gateway.ts builds a Hono application mounted at /api/v1 with route groups per business capability (/properties, /construction, /leases, /materials, /finance, /market-intel) plus a full production middleware pipeline: JWT auth + RBAC (auth.ts, ROLE_PERMISSIONS), tiered rate limiting (rate-limit.ts), OpenTelemetry tracing (tracing.ts), Prometheus metrics (metrics.ts), circuit breakers (circuit-breaker.ts), structured logging, and /health checks. It also ships a Kafka publisher/consumer with dead-letter handling (kafka.ts, CYBELE_KAFKA_TOPICS), a GraphQL schema (graphql/schema.ts), a WebSocket server with channel-authorization (websocket/server.ts), gRPC proto definitions (grpc/definitions.ts), an OpenAPI spec (openapi/cybele-api.yaml), and concrete route repositories including a DrizzlePropertyRepository and an InMemoryConstructionLedger with on-chain EVM input derivation.

The domain-agnostic utility foundation (libs/cybele/common/src), a pure-math package with no external runtime deps. geo.ts implements real WGS84 geodesy (haversine, bounding boxes, UTM Zone 30N ↔ WGS84 projection, polygon operations, and Ghana GPS digital-address parsing) against WGS84 ellipsoid constants; math.ts, dates.ts, and ids.ts provide money/number math, date helpers, and ID utilities; and carbon-esg.ts adds carbon/ESG accounting. The barrel (index.ts) re-exports math, dates, geo, and ids; carbon-esg lives in the package with its own test.

The construction-management engine (libs/cybele/construction/src). Its barrel exports scheduling (Critical Path Method forward/backward pass, PERT, look-ahead, WBS — all per PMI PMBOK in scheduling.ts), cost (earned-value), quality, progress, resource, and procurement. The package also contains field-technology modules not re-exported from the top barrel: drone.ts (flight-plan generation, photogrammetric point clouds, volumetric earthwork), ar-lidar.ts (AR-glasses BIM overlay, LiDAR-to-BIM, as-built deviation), and drone-inference.ts — a swappable YOLO / RT-DETR backend abstraction with a deterministic FixtureDroneInferenceBackend for tests and an OnnxDroneInferenceBackend that dynamic-imports onnxruntime-node for real image inference.

The domain-type foundation (libs/cybele/core/src), titled "Ghana Real Estate & Construction" in its header. types.ts defines branded ID types (PropertyId, PlotId, BuildingId, LeaseId, ContractorId, FundId, …) with factory functions plus the domain enums (PropertyStatus, GhanaRegion, LandTenure, ZoningClass, ValuationMethod, …); validators.ts provides the matching Zod schemas; and guards.ts and serializers.ts supply runtime type guards and (de)serialization. It is the lowest-level shared vocabulary every other Cybele library builds on.

The persistence layer (libs/cybele/db/src + drizzle/). schema.ts defines the Drizzle/Postgres tables — property status/type enums, spatial columns with explicit decimal precision/scale for coordinates, areas, and money — and relations; connection.ts and redis-config.ts provide the DB/Redis clients; seed.ts seeds reference data. The nine numbered SQL migrations under drizzle/ are real and domain-specific: initial schema, TimescaleDB IoT hypertables, partitioning, PostGIS plot boundaries, building spatial hierarchy, construction WBS, rent schedules, prefab design/orders/assembly, and competitor developments.

The architectural and engineering design engine (libs/cybele/design/src). The barrel exports structural (RC beam/column design per BS 8110 / Eurocode 2 with Ghana climate wind loads in structural.ts), mep (mechanical/electrical/ plumbing), sustainability (green-building scoring), bim, drawings, and design-intelligence. The package also carries two modules beyond the barrel: digital-twin.ts (a BIM-to-digital-twin pipeline with IoT binding and predictive-maintenance analytics) and generative.ts (parametric generative floor-plan/facade/massing design with constraint satisfaction tuned to Ghana's climate and regulations).

The real-estate deal-finance engine (libs/cybele/finance/src). Its core is genuine financial math: proforma.ts implements computeNPV, a Newton-Raphson computeIRR with bisection fallback (converging on |NPV| < 1e-8), plus sensitivity and Monte-Carlo development modelling. Surrounding modules cover mortgage, reit (NAV calculations reusing computeIRR), crowdfunding, and alternative-finance (rent-to-own scheme design). This is the deal/instrument layer — distinct from @cybele/financials, which models enterprise economics.

The enterprise/portfolio financial-modelling engine (libs/cybele/financials/src). Where finance prices individual deals, this library models the development business: proforma-models.ts defines structured CostBreakdown (land, acquisition, construction, contingency, professional fees, permits, financing, marketing, legal) and ReturnMetrics (ROC, ROE, equity multiple, IRR); cost-models.ts adds cost estimation; synergies.ts models inter-company transfer pricing and business-unit synergies; and financials-extended.ts extends the set. The barrel re-exports all four.

The hospitality / hotel-operations engine (libs/cybele/hospitality/src). revenue.ts computes standard hotel KPIs — ADR, RevPAR, occupancy, TRevPAR, GOPPAR — normalising any input period to a per-night basis (computeHotelKPIs); operations.ts handles operational management; and hospitality-extended.ts adds further capability. All three are exported from the barrel; the package is tagged type:facilities.

The industrial-park planning and operations engine (libs/cybele/industrial-parks/src). planning.ts models park zoning (ParkZone with manufacturing/logistics/services/amenities/green-space/ substation/water-treatment types, building-coverage and power-allocation constraints) and plot subdivision (ParkPlot with frontage/depth and lease rates); operations.ts covers park operations and warehouse.ts covers warehousing. The barrel exports planning, operations, and warehouse.

The civil-infrastructure engineering engine (libs/cybele/infrastructure/src). roads.ts implements the AASHTO-1993 flexible-pavement design method — solving the structural-number equation iteratively, with subgrade resilient modulus estimated from CBR (MR = 2555·CBR^0.64) and drainage coefficients chosen for Ghana's tropical climate. civil-works.ts covers earthworks/drainage and procurement.ts covers infrastructure procurement. The barrel exports roads, civil-works, and procurement.

The cross-domain bridge layer (libs/cybele/integration/src). It defines the typed contracts and bridge classes connecting Cybele to five sibling domains: brigid-bridges.ts (industrial manufacturing — prefab factory automation, SCADA, data-center power, predictive maintenance, with a stateful BrigidFactoryAutomationBridge), saraswati-bridges.ts (creative authoring), asase-bridges.ts, freya-bridges.ts, and maat-bridges.ts (governance/risk — portfolio oversight, financial consolidation, compliance, enterprise risk). Each bridge carries a BridgeHealthCheck/status model. The barrel re-exports all five.

The market-intelligence and analytics engine (libs/cybele/market-intel/src). pricing.ts builds quarterly hedonic-style price indices from PropertyTransaction records (median price-per-sqm by district/type, base period = 100); supply.ts models supply/absorption; economic-indicators.ts tracks Ghana macro drivers (construction costs, interest rates, infrastructure investment, urbanization, FDI, housing demand) into a unified macro dashboard; and market-extended.ts adds further analytics. The barrel exports pricing, supply, market-extended, and economic-indicators.

The building-materials engine (libs/cybele/materials/src), grounded in Ghana standards. concrete.ts carries GHANA_CONCRETE_MIXES (C15/C20/… mix-design proportions per cubic metre, per GS 298 / GS EN 206-1 with w/c ratios and target strengths) plus block-test result types; steel.ts, paint.ts, tiles.ts, and furniture.ts model their material classes, and cross-material.ts handles cross-material concerns. The barrel exports all six.

The prefabricated/modular-housing engine (libs/cybele/prefab/src). affordability.ts carries real Ghana regional housing-deficit data (GHANA_HOUSING_DEFICIT, sourced to GSS 2021 PHC / UN-Habitat / GREDA, ~1.8M national units) and computes affordability indices (price-to-income, DTI mortgage test) and prefab development ROI/IRR. modules.ts defines the module library, with production, logistics, and assembly covering manufacture and on-site assembly. The barrel exports modules, production, affordability, logistics, and assembly.

The property and asset-management engine (libs/cybele/property/src). valuation.ts implements multiple RICS-style methods — comparative sales (recency/proximity-weighted comparables), income capitalisation, DCF, cost approach, reconciliation, and a simplified AVM; lease.ts, tenant.ts, and maintenance.ts handle leasing, tenancy, and maintenance; analytics.ts adds portfolio analytics. The package also includes iot.ts — an IoT smart-building platform (occupancy sensing, HVAC/lighting optimization, leak/elevator/parking management). The barrel exports lease, tenant, maintenance, valuation, and analytics.

The property-technology engine (libs/cybele/proptech/src). blockchain-title.ts implements an on-chain land-title registry with NFT tokenization (ERC-721 / ERC-3643 T-REX), smart-contract leases, and cryptographic transfer verification using node:crypto ECDH/sign primitives, layered over a real wallet.ts (keccak256, EIP-191 digests, recoverAddress, verifyMessage); its TitleTenure enum models Ghana-specific tenures (Stool_Land, Family_Land, Vested). listing.ts/listing-extended.ts, crm.ts/crm-extended.ts, transactions.ts, and digital-experience.ts cover listings, lead CRM, transactions, and digital customer experience. The barrel exports all of these.

The site-selection and analysis engine (libs/cybele/site-analysis/src), the largest engine by file count. selection.ts runs multi-criteria decision analysis (MCDA) with sensitivity and highest-and-best-use analysis per RICS, composing infrastructure, demographics, risk, and land-registry (zoning-compliance and land-dispute-risk scoring); ai-selection.ts adds ML-style gradient-boosted site scoring, NLP search parsing, and price- appreciation prediction. The package additionally carries real external-data provider abstractions — dem-provider, ndvi-provider, borehole-provider, epa-monitoring-provider, and competitor-repository — each with its own spec. The barrel exports gis, demographics, infrastructure, risk, land-registry, and selection.

The shared test-utility library (libs/cybele/testing/src), tagged type:testing. fixtures.ts provides typed fixture factories built on @cybele/core branded-ID makers and domain enums (constructing Property, ResidentialProperty, GhanaAddress, GeoLocation, GeoPolygon, etc.), and mocks.ts supplies reusable mocks. The barrel re-exports both, giving the other Cybele libraries a single import for domain-accurate test data.