System design
Small composable layers, evidence-first generation.
The codebase keeps business logic independent from Cloudflare implementation details. Worker bindings are adapted at the edge, while domain modules remain pure and testable.
Code boundaries
| Layer | Path | Responsibility |
|---|---|---|
| Domain | src/domain | Pure logic for scoring, evidence packets, cards, verifier, review, filings, documents, and knowledge graph. |
| Services | src/services | Application workflows that compose domain functions with repositories, queues, and audit stores. |
| Storage | src/storage | D1 repository and row mapping. SQL stays out of the domain layer. |
| Ports | src/ports | Cloudflare binding adapters for Queues and R2. |
| HTTP | src/http | Routing, JSON parsing, and response shaping. |
| Worker entrypoint | src/index.js | Composes Cloudflare bindings into service dependencies. |
Cloudflare target shape
1
Cloudflare Pages serves the frontend and docs.
2
Workers expose internal and public APIs.
3
D1 stores normalized metadata and card records.
4
R2 stores raw market files, filing documents, parsed text, evidence packets, generated cards, and audit logs.
5
Queues run card-generation and verifier jobs asynchronously.
6
AI Gateway can be added later for model calls without changing the evidence-packet contract.