문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는 상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을 가리킨다. 고른 방법: 기계적으로 바꾼다. - 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고, 대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다. 옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은 링크 대상뿐이다(백엔드 1단계와 같은 예외). - 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`, `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과 CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와 review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토 작업 공간의 출처 표시라 그대로 둔다. 위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는 없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다. 검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록, CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시 쓴다) 밖에서 0건.
6.3 KiB
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.
src/ has nine top-level folders. The descriptions match the table in
the layer contract, which also names every import rule:
src/bootstrap— the composition root: runtime configuration, concrete adapter construction and the React mountsrc/apps— deployable apps: eachapp-module.tsdeclares an app and its context budget;template-app.tsis the app this build producessrc/contexts— bounded contexts: eachcontext-module.tsdeclares its app, route root and feature budgetsrc/features— removable vertical slices (src/features/<id>/{domain,application,contracts,adapters,presentation}) and the installed-feature catalogs (src/features/*.ts)src/presentation— generic UI and the inbound adapter: routes, layouts, the design system, pages and providerssrc/adapters— reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and moresrc/application— generic use cases, ports, policies and view-modelssrc/contracts— shared vocabulary and registries read by several layers, the workers and the build and release scriptssrc/platform— product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
Arrows point from the importing folder to the imported one. Every folder may
also import contracts and platform; only the main path is drawn.
flowchart LR
Bootstrap[bootstrap / composition root] --> Presentation[presentation]
Bootstrap --> Adapters[adapters]
Bootstrap --> Features[features]
Presentation --> Shell[app shell and route surfaces]
Shell --> Providers[session and theme providers]
Presentation -- app router only --> Apps[apps]
Apps --> Contexts[contexts]
Contexts --> Features
Features --> Application[application]
Presentation --> Application
Adapters --> Application
Application --> Contracts[contracts]
Contracts --> Platform[platform]
The enforced dependency rule points inward: presentation calls application use cases, adapters implement application ports, and only the composition root selects concrete adapters. Domain code lives inside each feature. 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:
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 with its own graph (the rules
live in .dependency-cruiser.json; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), 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 ports, adapters, and boundaries
- API contract, Schema, Mapper, and Server State
- Protobuf browser transports and REST Gateway
- Backend API and Server State handoff contract
- TypeScript, state, and data flow
- Routing, pages, and patterns
- Browser data capability completion ledger
- Browser file and origin storage
- Client cache and storage
- Realtime events, Web Push, and bounded polling
- Presigned transfer and Image CDN
- Server file capability infrastructure
- Frontend platform implementation roadmap