frontend 이미지는 nginx 공식 이미지라 root로 시작해 80번을 열고 worker를 nginx 사용자로 내린다. 그래서 Kubernetes에서 runAsNonRoot와 drop ALL을 둘 수 없다(k3s 성숙도 점검 2026-11-11, 7.5절). 운영 매니페스트는 allowPrivilegeEscalation: false만 두고 PSA restricted 경고를 낸다. runtime base를 nginxinc/nginx-unprivileged:1.27.5-alpine(digest 고정)으로 바꾼다. 예전 base와 같은 NGINX 1.27.5·Alpine이고 wget도 있어 HEALTHCHECK가 그대로 돈다. 파일을 고치는 동안만 root로 있다가 USER 101로 돌아간다. 생성되는 server 블록은 listen 8080이고, EXPOSE·HEALTHCHECK·dev-stack 포트 매핑도 8080으로 맞춘다. 버린 대안: Debian판 nginx-unprivileged. wget이 없어 HEALTHCHECK가 늘 실패한다. 80번을 그대로 두고 NET_BIND_SERVICE만 남기는 안도 버렸다. drop ALL을 못 하고 PSA restricted도 통과하지 못한다. 위험·한계: 이 이미지는 8080을 열므로 운영 매니페스트의 포트를 같이 바꿔야 한다. deploy/production/frontend-nonroot가 그 일을 하고, 기본 경로에는 넣지 않는다. dev-stack의 443·/etc/nginx/tls 부분은 이미지에 없는 파일을 쓰는 예전 상태 그대로다. 이 repo의 pnpm 게이트와 전체 docker build는 돌리지 않았다(heavy lock 대기가 길어 취소). 검증: desktop에서 이 Dockerfile의 runtime 단계를 그대로 쓰고, 빌드 단계만 운영 이미지 7a4e201의 dist와 conf(listen 8080으로 바꿈)로 대신해 이미지를 만들었다. --user 101 --cap-drop ALL --security-opt no-new-privileges --sysctl net.ipv4.ip_unprivileged_port_start=1024로 띄우면 GET /config.json 200, GET / 200, CapEff 0, NoNewPrivs 1이고, Docker health는 healthy다.
Tech Log Frontend
Initialized from clean-architecture-frontend-template revision
4dc033cf33a5b6173bbf960d5eb464a406dc4c92. The exact source identity is
recorded in template.lock.json.
A React/Vite TechLog application where architecture boundaries, integration behavior, release coherence, accessibility, performance, and operations are executable contracts rather than conventions.
Start locally
Requirements: the exact Node.js version in .nvmrc (currently 24.14.0) and
Corepack. The repository pins pnpm in package.json.
Product source, tests, build/quality scripts, and supported tool configuration
are TypeScript/TSX. allowJs is disabled. Node-side .ts scripts run directly
on the pinned Node 24 runtime and are checked with NodeNext resolution plus
erasable-syntax enforcement. Project-owned executable source contains no
JavaScript-family files; negative architecture, security, and type-compatibility
fixtures are TypeScript/TSX as well.
corepack pnpm install --frozen-lockfile
corepack pnpm dev
Runtime-public settings live in public/config.json and are validated before
the product tree mounts. Client secrets are forbidden.
TechLog experience
The default build mounts the source-faithful TechLog Public and Studio
experience. Public routes provide discovery, search, documents, topics,
projects, releases, and profile content. /studio provides the session-scoped
mock authoring workflow: create, edit, validate, preview, publish, unpublish,
and immutable publication history.
The 27 canonical route definitions are divided into PUBLIC and STUDIO
nested layouts. Studio authentication remains deliberately deferred; its mock
gateway state lasts for one Studio shell session and resets on a full document
load. The exact route, dependency, stylesheet, asset, and parity inventory is
recorded in
docs/operations/techlog-ui-migration-baseline.md.
corepack pnpm build emits a self-contained dist/server.mjs production
boundary. corepack pnpm preview --host 127.0.0.1 --port 4174 serves known
Public and Studio routes as SPA documents, preserves the in-shell Studio 404,
and returns source-exact raw 404 text/plain responses for missing Public
content. With the read-only source temp-copy server on 4375, run:
TECH_LOG_SOURCE_URL=http://127.0.0.1:4375 \
TECH_LOG_TARGET_URL=http://127.0.0.1:4174 \
corepack pnpm verify:tech-log-source-parity
Studio backend source
TECH_LOG_STUDIO_SOURCE (MOCK | HTTP) selects which StudioGateway
adapter the composition root wires up. It defaults to MOCK — the
session-scoped in-memory Studio described above — so the existing Studio
workflow and its test suites are unaffected unless the switch is deliberately
turned on. Setting it to HTTP wires the HTTP StudioGateway instead, which
calls the canonical @tech-log/studio-contract operations against
API_BASE_URL. With no backend reachable at that URL, Studio still boots and
its shell renders; the specific panels that need the backend show an inline
"failed to load" state rather than a blank screen or an unhandled exception.
The switch is a field on the versioned runtime config document
(RuntimeConfigV2), not a build-time flag:
config/runtime/{local,development,staging,production}.jsonare the deployment profilescorepack pnpm build(viascripts/generate-runtime-config.ts) materializes intodist/config.jsonfor a real build.corepack pnpm devdoes not run that step. Plainviteservespublic/config.json(andpublic/release-manifest.json) verbatim as dev fixtures — editingconfig/runtime/local.jsonalone has no effect onpnpm dev. To exerciseHTTPmode underpnpm dev, setTECH_LOG_STUDIO_SOURCEinpublic/config.jsondirectly.
The dev release manifest must declare the compiled contract set
Contract-set verification runs unconditionally at boot, before any adapter is
selected. It is not an HTTP-mode caveat: if public/release-manifest.json's
contractSet does not match the set the build compiled, corepack pnpm dev
does not start the app at all — it renders the fail-closed boot screen
(CONTRACT_SET_MISMATCH / CONTRACT_SET_PACKAGE_MISSING) in the default
MOCK mode too. A developer who runs pnpm dev and gets a boot error has a
broken dev server, however tidy the screen looks; treat it as a defect in the
fixture, never as expected behaviour.
The expectation comes from EXPECTED_CONTRACT_SET_PACKAGES
(src/features/installed-contract-contributions.ts), and a real build writes it
into dist/release-manifest.json from scripts/generate-contract-set.ts, so
production builds are always self-consistent. Only the hand-maintained dev
fixture can drift, and it drifts whenever either half moves — a regenerated
contract (new package digest or version) or a contribution added to or removed
from installed-contract-contributions.ts. Two things keep it honest:
corepack pnpm generate:tech-log-contractrefreshes the fixture'scontractSetblock as its last step, so regenerating the contract can never leave the two out of step.corepack pnpm generate:dev-release-manifestrefreshes the same block on its own, for the contribution-list case that does not go through contract generation.corepack pnpm check:dev-release-manifestis the gate. It compares the fixture'ssetAlgorithm,setDigestand package set against the compiled set and fails on any difference. It runs in CI as part of FE-GATE-010, which is what catches the changes the generation step cannot see.
TechLog contract generation
The Studio HTTP contract is vendored from a canonical OpenAPI source, not hand-written:
corepack pnpm generate:tech-log-contractregeneratessrc/features/tech-log/contracts/studio/studio-api.openapi.yaml,generated.ts, andcanonical-source.jsonfrom the canonicaltech-log-design-packagerepository (path fromTECH_LOG_DESIGN_PACKAGE, default/home/donghyeon/workspace/tech-log-design-package). It needs that repository checked out locally and network access, because type generation runs in an isolatedpnpm dlxsandbox (this repo pins TypeScript 7, which has no classic compiler API foropenapi-typescriptto use). Run it after the canonical contract changes, then commit the regenerated files.corepack pnpm check:tech-log-contractis the drift gate: it hashes the vendored yaml against the recorded digest and confirms every recordedoperationIdis present in both the yaml and the generated types. It needs neither the canonical repository nor the network, so it runs in CI and in this sandbox. Run it any time to confirm the vendored contract has not drifted from what was last generated.
Architecture
This repository is a Frontend Application Foundation: a starter/composition skeleton plus a reusable capability platform. Platform capabilities stay horizontal while product business features use vertical slices.
Dependencies point inward:
presentation -> application -> domain
adapters -----^
bootstrap composes concrete adapters
feature use case -> feature port <- feature-owned capability binding
See
docs/architecture/frontend-application-foundation.md,
docs/architecture/overview.md, docs/architecture/layers.md, and
docs/architecture/starter-experience.md. TechLog is one feature boundary
under src/features/tech-log. Its immutable Public catalog and session-scoped
Studio mock gateway are injected through the application feature input;
Public and Studio presentation code shares the typed content renderer without
importing concrete adapters. The retained reference feature remains a
non-product platform contract fixture and can be removed without changing the
TechLog route set.
Platform capability review
The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path:
- platform capability review
- ports, adapters, and feature boundaries
- REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State
- Protobuf browser transports and REST Gateway
- backend API and Server State handoff contract
- TypeScript, state ownership, and data flow
- routing, page templates, and reusable patterns
- browser data capability completion ledger
- browser file and origin-storage platform
- client cache and storage
- realtime events, Web Push, and bounded polling
- presigned transfer, resumable upload, streaming download, and Image CDN
- server file capability infrastructure
- design-system platform
- frontend platform testing strategy
- implementation roadmap
These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass.
Verification
Common local checks:
corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:contract
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci
corepack pnpm exec vitest run tests/features/tech-log
corepack pnpm exec playwright test tests/e2e/tech-log-public-discovery.spec.ts tests/e2e/tech-log-studio-workflow.spec.ts tests/e2e/tech-log-responsive.spec.ts tests/e2e/tech-log-accessibility.spec.ts --project=chromium
corepack pnpm test:visual
test:all is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run corepack pnpm test:system only on the
compatible Linux assurance host described in
docs/testing/taxonomy.md.
check:types는 source, Node scripts/config와 tests를 분리된 TypeScript
project로 모두 검사한다. type/architecture/security/registry의 invalid
fixture는 config/ci/gates.json에서 “실패해야 통과”하는 negative gate로
실행된다. 도구 호환성 결정은
VD-01에 기록돼
있다.
Application feature input은 module augmentation으로 닫힌 ID와 정확한 input
shape를 제공하며, 공통 Result<Value, Failure = AppFailure>는 error registry의
failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는
TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고
runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import,
parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용
TypeScript/TSX negative fixture로도 검증된다.
Install the pinned Playwright browser engines before the first cross-browser run:
corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
review:a11y-manualneeds a signed human keyboard/focus/screen-reader review for all 27 registered routes:NOT_FOUND,TECH_LOG_CASE,TECH_LOG_EXPLORE,TECH_LOG_EXPLORE_KIND,TECH_LOG_HOME,TECH_LOG_PROFILE,TECH_LOG_PROJECT,TECH_LOG_PROJECTS,TECH_LOG_PROJECT_ACTIVITY,TECH_LOG_PROJECT_DECISIONS,TECH_LOG_PROJECT_RECORDS,TECH_LOG_QUESTION,TECH_LOG_REFERENCE,TECH_LOG_RELEASE,TECH_LOG_RELEASES,TECH_LOG_SEARCH,TECH_LOG_STUDIO_DOCUMENTS,TECH_LOG_STUDIO_DOCUMENT_EDIT,TECH_LOG_STUDIO_DOCUMENT_NEW,TECH_LOG_STUDIO_DOCUMENT_PREVIEW,TECH_LOG_STUDIO_DOCUMENT_PUBLISH,TECH_LOG_STUDIO_DOCUMENT_VALIDATION,TECH_LOG_STUDIO_HOME,TECH_LOG_STUDIO_NOT_FOUND,TECH_LOG_STUDIO_PUBLICATIONS,TECH_LOG_STUDIO_PUBLICATION_PREVIEW,TECH_LOG_TOPIC.verify:documentationderives that list from the route registry and fails if this paragraph falls behind it.collect:web-vitals-evidencestaysFAIL_UNVERIFIEDuntil a reviewed minimum eligible-sample threshold and 28 days of production data exist.
Live release verification additionally requires HOSTING_BASE_URL.
CI and evidence
The 27-gate registry is config/ci/gates.json; the Gitea workflow is
.gitea/workflows/quality-gates.yml. It follows:
MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
DOCUMENTATION_READY is independent. No gate is downgraded to a warning.
Machine-readable evidence is written below artifacts/; generated evidence is
ignored by Git while .gitkeep files preserve the taxonomy.
Operational details are in docs/operations/, with incident procedures in
docs/runbooks/.