80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
# Architecture overview
|
|
|
|
This Mermaid view is a repository-local implementation projection. The
|
|
`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
|
|
in `review-ledger.json`, not automatically to edits in this file.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Bootstrap[bootstrap / composition root] --> Presentation[presentation]
|
|
Bootstrap --> Adapters[adapters]
|
|
Presentation --> Shell[app shell and route surfaces]
|
|
Shell --> Providers[session and theme providers]
|
|
Presentation --> Application[application]
|
|
Adapters --> Application
|
|
Application --> Domain[domain]
|
|
Contracts[contract registries] --> Bootstrap
|
|
Contracts --> Adapters
|
|
Contracts --> Presentation
|
|
```
|
|
|
|
The enforced dependency rule points inward: presentation calls application use
|
|
cases, adapters implement application ports, and only the composition root
|
|
selects concrete adapters. Contract registries are the named source for routes,
|
|
API operations, environment values, storage keys, errors, queries, telemetry,
|
|
and release tokens. Installed feature contributions extend those registries
|
|
without making the generic application or router import a concrete feature
|
|
implementation.
|
|
|
|
In ports-and-adapters terms, `presentation` is the current inbound adapter and
|
|
`adapters` contains the current outbound implementations. The production
|
|
composition exposes an application input API to React while keeping concrete
|
|
output ports inside application closures:
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Driver[User, route, browser event] --> Inbound[React inbound adapter]
|
|
Inbound --> Input[Application input API]
|
|
Input --> UseCase[Use cases]
|
|
UseCase --> Output[Application output ports]
|
|
Output --> Outbound[HTTP, auth, storage, query, telemetry adapters]
|
|
Bootstrap2[Composition root] -. selects and injects .-> Input
|
|
Bootstrap2 -. selects and injects .-> Outbound
|
|
```
|
|
|
|
The executable route tree is mounted only after runtime configuration and
|
|
release-manifest coherence pass. `ApplicationProvider` receives the composed
|
|
application API; concrete session, storage, telemetry, diagnostics, and release
|
|
ports are not returned to feature pages. TanStack Query is isolated behind the
|
|
presentation query adapter, while its provider remains React infrastructure.
|
|
The module-augmented feature registry gives each installed feature a closed ID
|
|
and exact input type.
|
|
|
|
Route contracts/codecs, the route-input provider, and lazy runtime modules are
|
|
separate modules so feature pages do not import the router that loads them.
|
|
Expected application failures use the shared `Result`/`AppFailure` contract.
|
|
The architecture gate analyzes TS/TSX imports independently of
|
|
dependency-cruiser, rejects local JavaScript-family specifiers and executable
|
|
JavaScript-family files, and fails on unresolved imports, parse failures,
|
|
forbidden layer edges, or cycles. The remaining project-owned work includes
|
|
selecting and verifying real hosting, identity, telemetry, vulnerability and
|
|
signing providers, plus backend/provider/browser/operations evidence for each
|
|
selected optional capability; the repository does not fabricate that evidence.
|
|
Use the following
|
|
documents for implementation details and project integration work:
|
|
|
|
- [Frontend platform capability review](./frontend-platform-capability-review.md)
|
|
- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
|
- [API contract, Schema, Mapper, and Server State](./api-contract-schema-mapper-and-server-state.md)
|
|
- [Protobuf browser transports and REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)
|
|
- [Backend API and Server State handoff contract](./backend-api-and-server-state-contract.md)
|
|
- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md)
|
|
- [Routing, pages, and patterns](./routing-pages-and-patterns.md)
|
|
- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)
|
|
- [Browser file and origin storage](./browser-file-and-origin-storage.md)
|
|
- [Client cache and storage](./client-cache-and-storage.md)
|
|
- [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)
|
|
- [Presigned transfer and Image CDN](./presigned-transfer-and-image-cdn.md)
|
|
- [Server file capability infrastructure](./server-file-capability-infrastructure.md)
|
|
- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md)
|