# @cybele - Real Estate & Construction Intelligence

Cybele is Oshun's real estate and construction intelligence domain, spanning
site analysis, architecture, construction delivery, property operations,
building materials, finance, and PropTech workflows for Ghana's built
environment.

## Overview

| Aspect              | Description                             |
| ------------------- | --------------------------------------- |
| **Domain**          | Real Estate & Construction Intelligence |
| **Scope Tag**       | `scope:cybele`                          |
| **API Port**        | 4027                                    |
| **Database Schema** | `cybele`                                |

## Capabilities

- **Property Intelligence**: Residential, commercial, industrial, and mixed-use
  property lifecycle management
- **Site Analysis**: GIS-backed parcel, zoning, accessibility, and market
  feasibility analysis
- **Design & BIM**: Tropical-climate architectural design, BIM entities, and
  generative design helpers
- **Construction Delivery**: Project schedules, work breakdown structures,
  progress tracking, cost control, and earned value metrics
- **Prefab Housing**: Modular housing design, factory ordering, and assembly
  planning for affordable housing delivery
- **Materials & Manufacturing**: Inventory, production batches, quality control,
  carbon factors, and supply planning for building materials
- **Real Estate Finance**: Mortgage, REIT, crowdfunding, investor allocation,
  and valuation workflows
- **Operations & PropTech**: Tenant lifecycle, leasing, listings, inquiries,
  virtual tours, and portfolio operations

## Libraries

```text
libs/cybele/
├── api/                # API gateway, REST routing, health, metrics, tracing
├── common/             # Shared helpers and domain utilities
├── construction/       # Construction project management and progress logic
├── core/               # Core domain types, validators, guards, serializers
├── db/                 # Drizzle schema, migrations, seeds, and database config
├── design/             # Architectural design, BIM, and generative layout tools
├── finance/            # Mortgages, REITs, affordability, and financing logic
├── financials/         # Cross-business-unit financial models
├── hospitality/        # Hospitality property inventory, bookings, and rates
├── industrial-parks/   # Industrial park tenants, utilities, and infrastructure
├── infrastructure/     # Civil infrastructure and road project intelligence
├── integration/        # Cross-domain integration bridges
├── market-intel/       # Price indices, comparables, forecasts, and analytics
├── materials/          # Building materials inventory, batches, and QC
├── prefab/             # Modular housing designs, orders, and assembly tracking
├── property/           # Portfolio, leases, tenants, maintenance, and units
├── proptech/           # Listings, inquiries, tours, agents, and transactions
├── site-analysis/      # GIS, zoning, location scoring, and parcel analysis
└── testing/            # Fixtures, mocks, and test utilities
```

## Applications

```text
apps/cybele/
├── api/          # Cybele API application surface
├── factory/      # Prefab and materials operations app
├── marketplace/  # PropTech marketplace app
├── portfolio/    # Property portfolio operations app
└── projects/     # Development and construction project app
```

## Quick Start

### Using Core Types

```typescript
import { createPropertyId, PropertyStatus } from '@cybele/core';

const propertyId = createPropertyId('prop_accra_airport_city_001');

const status: PropertyStatus = 'Completed';

console.log({ propertyId, status });
```

### Running Locally

```bash
# Test core domain types and validators
pnpm nx test @cybele/core

# Run API library tests
pnpm nx test @cybele/api

# Lint the deployable API app surface
pnpm nx lint @cybele/app-api
```

## API Endpoints

| Method | Endpoint                             | Description                          |
| ------ | ------------------------------------ | ------------------------------------ |
| GET    | `/health`                            | Service health check                 |
| POST   | `/v1/properties`                     | Create a property record             |
| GET    | `/v1/properties/:id`                 | Retrieve property details            |
| PATCH  | `/v1/properties/:id`                 | Update property metadata             |
| POST   | `/v1/construction/projects`          | Create a construction project        |
| GET    | `/v1/construction/projects/:id`      | Retrieve project status              |
| POST   | `/v1/leases`                         | Execute a lease workflow             |
| GET    | `/v1/market-intel/price-indices`     | Query market price indices           |
| POST   | `/v1/site-analysis/parcels/evaluate` | Evaluate parcel feasibility          |
| WS     | `/v1/construction/projects/:id/live` | Real-time construction progress feed |

## Events

| Event                              | Description                         |
| ---------------------------------- | ----------------------------------- |
| `cybele.property.created`          | Property record created             |
| `cybele.property.valued`           | Valuation completed                 |
| `cybele.lease.executed`            | Lease agreement executed            |
| `cybele.project.created`           | Construction project created        |
| `cybele.project.progress.updated`  | Construction progress changed       |
| `cybele.materials.batch.completed` | Materials production batch finished |
| `cybele.prefab.order.scheduled`    | Prefab factory order scheduled      |
| `cybele.title.transfer.verified`   | Land title transfer verified        |

## Configuration

```bash
# Required
CYBELE_DATABASE_URL=postgresql://...?schema=cybele
REDIS_URL=redis://localhost:6379

# Storage
CYBELE_DOCUMENT_BUCKET=oshun-cybele-documents
CYBELE_DRAWINGS_BUCKET=oshun-cybele-drawings
CYBELE_SITE_PHOTOS_BUCKET=oshun-cybele-site-photos

# External integrations
GHANA_LANDS_COMMISSION_API_URL=https://...
GHIPSS_API_URL=https://...
MOBILE_MONEY_API_URL=https://...

# Cross-domain
BRIGID_API_URL=http://localhost:4010
SARASWATI_API_URL=http://localhost:4011
ASASE_API_URL=http://localhost:4012
FREYA_API_URL=http://localhost:4013
MAAT_API_URL=http://localhost:4014
```

## Local Development

Start the Cybele infrastructure stack before running API or integration tests:

```bash
docker compose -f docker/docker-compose.cybele.yml up -d

pnpm nx test @cybele/db
pnpm nx lint @cybele/app-api
```

For broad verification on constrained hosts, prefer targeted Cybele commands or
Nx affected runs before full workspace gates.

## Related Packages

- `@contracts/cybele` for Zod schemas, API contracts, and domain events
- `@cybele/testing` for fixtures and test helpers
- `apps/cybele/api` for the deployable Cybele API surface
