API — cœur métier¶

Monolithe NestJS + Fastify (projects/api, @bricks/api). Migration progressive vers src/__new/modules/.

Prod : https://api.bricks.co — 5 replicas Railway, région europe-west4.

Diagramme domaines¶

flowchart TB
  subgraph invest["Investisseur"]
    onboarding["Onboarding / KYC"]
    wallet["Wallet & transactions"]
    portfolio["Portfolio"]
    primary["Achat primaire / réservations"]
    marketplace["Marketplace"]
    referral["Parrainage & gift cards"]
    taxation["Fiscalité & documents"]
  end

  subgraph property["Projet immobilier"]
    funding["Collecte / funding"]
    schedule["Échéancier & remboursements"]
    charts["Charts & actualités"]
    spv["SPV"]
  end

  subgraph pdp["Porteur de projet"]
    finreq["Demande de financement"]
    projowner["Gestion post-approbation"]
  end

  subgraph admin["Administration"]
    adminmod["Admin actions"]
    flags["Feature flags"]
    internal["APIs internes / M2M"]
  end

  subgraph payments["Paiements"]
    lemonway["Lemonway"]
    checkout["Checkout.com"]
    moneyin["Money-in / retraits"]
  end

  invest --> payments
  property --> payments
  pdp --> property
  admin --> invest
  admin --> property

Stack technique¶

Couche	Technologie
Framework	NestJS 11 + Fastify 5
ORM legacy	TypeORM (`src/db/entities/`)
Query builder (nouveau)	Kysely (`src/__new/lib/kysely/`)
Validation	`idonttrustlikethat`, Zod (espace-fi)
Jobs	Graphile Worker (Postgres)
Cache	Redis (`ioredis`)
Migrations	Flyway (`migration/flyway/`)
Contrats partagés	`@bricks-common/api-communication*`

Structure code¶

projects/api/src/
├── main.ts                 # Entrée HTTP
├── app.module.ts           # Wiring controllers
├── customers/, marketplace/ …   # Routes legacy
└── __new/
    ├── modules/<domain>/   # Architecture cible
    │   ├── business/
    │   ├── model/
    │   ├── repository/
    │   └── service/
    └── lib/                # postgres, kysely, providers, graphile-worker

Couches module : business → repository → service → controller. Détail : projects/api/.cursor/rules/api-conventions.mdc.

Domaines principaux¶

Domaine	Modules (exemples)
Investissement primaire	`primary-purchase`, `property-funding`, `bricks-reservation`
Lifecycle bien	`property-creation`, `property-repayment`, `property-payment-schedule`
Paiements	`money-in`, `lemonway-p2p`, `lemonway-withdraw`, `lemonway-account`
Investisseur	`investor-onboarding`, `wallet-transactions`, `portfolio`, `investor-taxation`
PDP	`project-financing-request`, `project-owner`, `pdp-auth`
Admin	`administration`, `feature-flag`, `admin-action`
Interne	`internal-core`, `internal-investor`, `internal-project`

Cartographie complète : projects/api/.cursor/rules/domain-map.mdc.

Workers (processus séparés)¶

Même image Docker que l'API, services Railway distincts (projects/api/worker/).

Worker	Flag env	Rôle
Graphile cron	`IS_GRAPHILE_CRON_WORKER`	Sync Lemonway, échéancier, payouts, Neon scale…
Graphile queue	`IS_GRAPHILE_QUEUE_WORKER`	Jobs dynamiques (auto-funding…)
Pending / Played P2P	`IS_PENDING/PLAYED_LEMONWAY_P2P_WORKER`	Cycle P2P Lemonway
Bricks assignation / P2P	`IS_BRICKS_*_WORKER`	Assignation briques, création P2P
Réservations	`IS_RESERVATION_*_WORKER`	Confirm / expire réservation CB
PDF	`IS_PDF_GENERATOR_WORKER`	Génération PDF async

Liste complète des crons : À compléter.

Flux métier — achat de briques (simplifié)¶

sequenceDiagram
  participant App as App investisseur
  participant API as API
  participant DB as Postgres
  participant LW as Lemonway
  participant W as Workers

  App->>API: Achat / réservation
  API->>DB: Transaction + réservation
  API->>LW: Init paiement
  LW-->>API: Webhook
  API->>W: Job assignation
  W->>DB: Briques assignées
  W->>LW: P2P confirmé
  API-->>App: Succès

Détail par domaine : docs co-localisées sous projects/api/src/**/docs/.

APIs internes¶

Préfixe : /internal/<domain>
Auth : x-api-key (Auth — API keys)
OpenAPI : GET /internal/docs/json

Consommateurs : À compléter (gestion défauts, IA, site vitrine…).

À compléter¶

Sujet	Owner	Notes
Read replica — quelles routes	À compléter	`DATABASE_USER_RO`
État migration TypeORM → Kysely par domaine	À compléter
SLAs / timeouts par intégration critique	À compléter