agentic-dev 0.1.0 → 0.2.0

package/sdd/99_toolchain/02_policies/convention-storage-policy.md

@@ -0,0 +1,26 @@
+# Convention Storage Policy
+
+## Purpose
+
+저장소 전반에서 반복 참조되는 컨벤션, 워크플로우, 실행 규약의 정본 위치를 고정한다.
+
+## Rules
+
+- 공통 컨벤션의 정본은 항상 `sdd/99_toolchain/02_policies`에 저장한다.
+- `AGENTS.md`에는 실행 시 반드시 기억해야 할 짧은 핵심 규칙만 둔다.
+- `sdd/`는 history 저장소가 아니라 overwrite-only current-state delivery system으로 유지한다.
+- `sdd/02_plan`의 active planning은 `01_feature`, `02_screen`, `03_architecture`, `06_iac`, `10_test` 기준 durable 문서를 직접 갱신한다.
+- feature 계획은 `<domain>_todos.md`, screen 계획은 `<service>_todos.md` 파일을 single source of truth로 사용한다.
+- 컨벤션 관련 변경은 다음 순서를 따른다.
+  1. `sdd/99_toolchain/02_policies` 문서를 먼저 수정한다.
+  2. 필요한 경우에만 `AGENTS.md`, 런북, 템플릿, 자동화 문서를 최소 범위로 동기화한다.
+- 저장소 루트 하네스(`.codex`, `.claude`)는 toolchain 정책을 구현하는 자산으로 취급한다.
+- 하네스 사용법, 자동화 진입점, 템플릿화 가능한 예시는 `sdd/99_toolchain/01_automation`에 정리한다.
+- Playwright suite registry와 canonical runner도 `sdd/99_toolchain/01_automation`이 소유한다.
+
+## Canonical References
+
+- 워크플로우/배포 규칙: `main-push-before-dev-deploy-policy.md`
+- compose/runtime 기준선: `compose-runtime-baseline-policy.md`
+- 회귀 검수 규칙: `regression-verification-policy.md`
+- 하네스 설명: `../01_automation/harness-layout.md`

package/sdd/99_toolchain/02_policies/main-push-before-dev-deploy-policy.md

@@ -0,0 +1,27 @@
+# Main Push Before DEV Deploy Policy
+
+## Purpose
+
+템플릿 저장소에서도 `branch -> main -> DEV` 반영 순서를 고정하고, 완료된 branch를 retire해 재현 가능성과 추적 가능성을 확보한다.
+
+## Required Order
+
+1. 관련 작업에 맞는 work branch를 생성한다.
+2. 관련 변경을 구현하고 work branch를 origin에 push한다.
+3. root compose baseline 또는 해당 검증 surface build를 확인한다.
+4. 관련 변경을 `main`에 반영한다.
+5. Git 원격 `main` push를 완료한다.
+6. 그 커밋 기준으로 `DEV(개발계)` 배포를 수행한다.
+7. 배포된 DEV 환경에서 실제 동작을 검증한다.
+8. 필요한 SDD 문서를 현재 상태 기준으로 갱신한다.
+9. 완료된 local/remote work branch를 삭제한다.
+
+## Rules
+
+- `DEV` 반영이 필요한 작업은 task-fit work branch를 먼저 만들고 branch push를 남긴다.
+- `DEV` 반영이 필요한 작업은 `main` push 이전에 선배포하지 않는다.
+- 수동 배포 단계여도 `branch push -> build -> main merge/push -> DEV 배포 -> DEV 검증 -> 문서 갱신` 순서를 유지한다.
+- 작업 완료 전 최소 정합성 체크로 `관련 검증 명령`, `worktree clean 상태`, `최종 변경의 main 포함 여부`를 확인한다.
+- 완료된 작업은 `main` 반영 후 local branch와 remote branch를 모두 삭제한다. 사용자가 branch 보존을 명시한 경우만 예외다.
+- 검증 중 문제가 발견되면 다시 `수정(branch) -> branch push -> build -> main merge/push -> DEV 재배포 -> DEV 재검증`을 반복한다.
+- 템플릿 샘플 앱/서버도 실제로 부팅되고 검증 가능한 상태를 유지한다.

package/sdd/99_toolchain/02_policies/otro-orchestration-policy.md

@@ -0,0 +1,30 @@
+# OTRO Orchestration Policy
+
+## Purpose
+
+This repository treats OTRO (Overlap-Tolerant Residual Orchestration) as a reusable toolchain runtime for repository-wide artifact-grounded development.
+
+## Canonical Terms
+
+- `loop`: the top-level OTRO control cycle
+- `step`: the execution slice grouped inside a plan for one loop frontier
+- `loop_done`: the current plan backlog is exhausted
+- `run_done`: a fresh repository-wide rescan after `loop_done` yields no materially new tasks
+- `scope_done`: `run_done` plus scope-level deployment and verification gates pass
+- task IDs: `T{step}{ordinal}` canonical numbering, rewritten per step before a plan is persisted
+
+Obsolete alternate field names must not appear in runtime contracts, prompts, plans, or docs. Use `step`, `steps`, and `scope_done` only.
+
+## Runtime Rules
+
+- OTRO plans must keep run-local state under `.codex/skills/otro/runs/<run-name>/`.
+- The canonical plan schema is `.codex/skills/otro/schemas/step_plan.schema.json`.
+- OTRO runtime must resolve the target repository from run-local configuration or run ancestry, not from a skill directory hard-binding.
+- New OTRO plans must emit `step` on tasks and `steps` on grouped frontier entries.
+- No compatibility adapter is allowed for obsolete field names. Existing historical evidence may stay as history, but the live runtime must not read or write those fields.
+
+## Template Ownership
+
+- The canonical OTRO skill assets for downstream repositories live under `.codex/skills/otro/`.
+- Downstream repositories should copy or vendor the OTRO skill from this template surface instead of inventing repo-local variants.
+- When OTRO terminology or contracts change, update this policy and the template skill together.

package/sdd/99_toolchain/02_policies/regression-verification-policy.md

@@ -0,0 +1,22 @@
+# Regression Verification Policy
+
+## Purpose
+
+템플릿 저장소에서도 회귀 검수 범위를 direct target에 한정하지 않고, retained current-state workflow로 고정한다.
+
+## Rules
+
+- `sdd` 작업은 direct target verification만으로 완료 처리하지 않는다.
+- 회귀 검수 범위는 `sdd/02_plan/10_test/regression_verification.md`를 기준으로 direct, upstream, downstream, shared surface까지 선택한다.
+- shared route, shell, auth/session, component, contract, generated asset, builder output을 변경한 경우 adjacent consumer와 shared surface를 함께 검수한다.
+- Playwright exactness suite가 있는 screen/local UI surface는 `sdd/99_toolchain/01_automation/run_playwright_exactness.py`를 canonical local gate로 사용한다.
+- direct `npx playwright test ...` 호출은 디버깅 예외로만 쓰고, retained verification command는 toolchain wrapper 기준으로 남긴다.
+- 자동화가 없는 회귀 surface는 가능한 command/manual verification으로 대체하고, automation gap은 residual risk로 남긴다.
+- 선택한 회귀 검수 범위, 실행한 check, 생략 사유, residual risk는 `sdd/02_plan`, `sdd/03_build`, `sdd/04_verify`에 current-state로 유지한다.
+
+## Canonical References
+
+- `AGENTS.md`
+- `.codex/skills/sdd/SKILL.md`
+- `sdd/99_toolchain/01_automation/README.md`
+- `sdd/02_plan/10_test/regression_verification.md`

package/sdd/99_toolchain/03_templates/.gitkeep

@@ -0,0 +1 @@
+

package/sdd/99_toolchain/03_templates/asset_recipe_manifest.example.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+SCREEN_SPEC = ROOT / "sdd/01_planning/02_screen/mobile_screen_spec.pdf"
+OUTPUT_DIR = ROOT / "sdd/99_toolchain/03_templates/generated_assets"
+
+# Template example output lives under `03_templates/generated_assets`.
+# Replace this path with the consuming project's runtime asset directory.
+
+
+ASSET_RECIPES = [
+    {
+        "id": "example-brand-lockup-source",
+        "source": {"kind": "pdf_page", "path": SCREEN_SPEC, "page": 2, "dpi": 150},
+        "crop_box": (294, 750, 738, 1151),
+        "transparent_white_threshold": 245,
+        "trim": True,
+        "children": [
+            {
+                "id": "example-brand-lockup",
+                "output": OUTPUT_DIR / "example-brand-lockup.svg",
+            },
+            {
+                "id": "example-brand-mark",
+                "crop_box": (123, 0, 288, 180),
+                "output": OUTPUT_DIR / "example-brand-mark.svg",
+            },
+            {
+                "id": "example-brand-wordmark",
+                "crop_box": (50, 324, 363, 381),
+                "output": OUTPUT_DIR / "example-brand-wordmark.svg",
+            },
+        ],
+    }
+]

package/sdd/99_toolchain/03_templates/generated_assets/README.md

@@ -0,0 +1,11 @@
+# Example Generated Assets
+
+## Role
+
+- 이 폴더는 `스펙에셋빌더` example manifest 실행 결과를 저장한다.
+- template consumer는 이 산출물을 golden sample로 보고 자신의 project-specific output 경로로 치환하면 된다.
+
+## Regeneration
+
+- `python3 sdd/99_toolchain/01_automation/spec_asset_builder.py --manifest sdd/99_toolchain/03_templates/asset_recipe_manifest.example.py --verify-exact`
+- 또는 `python3 sdd/99_toolchain/01_automation/build_asset_recipes.py --verify-exact`

package/sdd/99_toolchain/03_templates/generated_assets/example-brand-lockup.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="444" height="273" viewBox="0 0 444 273" fill="none" role="img" aria-hidden="true">
+  <image width="444" height="273" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbwAAAERCAYAAAAAMhLvAAAEe0lEQVR4nO3dQUrDUBRA0Uaz/3VWpDpIUSftd2AXIEJMm3sOZNDBI2+QcElo6bS8HccBAHbuaesFAOA/CB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQMJ8nZ633gEAVjeNMbbeAQBW55UmAAmCB0CC4AGQIHgAJAgeAAmCB0CC4AGQIHgAJAgeAAmCB0CC4AGQIHgAJAgeAAmCB0CC4AGQMB9fXv0hHgC7N59O71vvAACrm5bzlyc8AHZvvlwuW+8AAKubxvCAB8D+zcv5c/x8WXPcjul2/PbzI81e/3Aes/c/+0jXoNn7vY7M7v1+nZbzxzgAwM75HR4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACYIHQILgAZAgeAAkCB4ACd/iAv4AZg+FSAAAAABJRU5ErkJggg==" />
+</svg>

package/sdd/99_toolchain/03_templates/generated_assets/example-brand-mark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="165" height="180" viewBox="0 0 165 180" fill="none" role="img" aria-hidden="true">
+  <image width="165" height="180" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKUAAAC0CAYAAAD1oezkAAACRElEQVR4nO3bsU6EQBRAUVj5/+9cY1YLiG7DjoU2mGhhwy3OSSgImfCKmyEhMK+v1zFByOXsAeAnUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnKWx/x09gxwMI8xzp4BDjy+yRElOaIkR5TkiJIcUZIjSnJESY4oyRElOaIkR5TkiJIcUZIjSnKW6/OLDypJWW63t7NngIN53e52SlKWfd/PngEO/KNDzrJuH2Oa5unrGN/Hb+ePP67V1l7+cR9rC2vndXu3VZLiPSU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJESU5oiRHlOSIkhxRkiNKckRJjijJ+QQO+HVFgvyROwAAAABJRU5ErkJggg==" />
+</svg>

package/sdd/99_toolchain/03_templates/generated_assets/example-brand-wordmark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="313" height="57" viewBox="0 0 313 57" fill="none" role="img" aria-hidden="true">
+  <image width="313" height="57" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATkAAAA5CAYAAABNllxFAAAAXElEQVR4nO3BAQ0AAADCoPdPbQ8HFAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwKEBFwwAAbnbqkcAAAAASUVORK5CYII=" />
+</svg>

package/sdd/99_toolchain/03_templates/playwright_exactness_manifest.example.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+PLAYWRIGHT_SUITES = [
+    {
+        "id": "service-screen-batch",
+        "spec": "service-screen-batch.spec.js",
+        "kind": "screen-exactness",
+        "service": "mobile",
+        "targets": ["SERVICE-S001", "SERVICE-S002"],
+        "description": "example screen exactness batch",
+    },
+    {
+        "id": "shared-shell-regression",
+        "spec": "shared-shell-regression.spec.js",
+        "kind": "shared-ui-regression",
+        "service": "platform",
+        "targets": ["shared-shell"],
+        "description": "example shared shell regression batch",
+    },
+]

package/sdd/99_toolchain/README.md

@@ -0,0 +1,23 @@
+# Toolchain
+
+`99_toolchain`은 SDD 산출물을 만들고 검증하는 generator, harness, 정책 문서를 둔다.
+
+## Structure
+
+- `01_automation`
+  - SDD generator, parity harness, projection 문서, capture automation, agentic repo contract
+- `02_policies`
+  - 저장소 공통 규칙의 정본
+- `03_templates`
+  - 재사용 가능한 템플릿 자산
+
+## Rule
+
+- planning 산출물은 `01_planning`에 둔다.
+- 그 planning 산출물을 생성하거나 검증하는 스크립트와 asset은 `99_toolchain`에 둔다.
+- screen spec generator, capture policy, manifest는 `01_automation`에 둔다.
+- 정책 문서는 `02_policies`를 정본으로 사용하고, `AGENTS.md`에는 핵심 실행 규칙만 요약한다.
+- compose/runtime 기준선은 `02_policies/compose-runtime-baseline-policy.md`를 정본으로 사용한다.
+- 현재 canonical screen toolchain은 `build_screen_spec_pdf.py`, `capture_screen_assets.mjs`, `screen_spec_manifest.py`다.
+- Claude/Codex/Ralph 하네스는 저장소 루트 `.claude`, `.codex`, `.agent`에 두고, 그 계약 설명은 `01_automation`과 `02_policies`에 둔다.
+- `sdd/03_build`는 AST-style runtime tree current-state를 유지하고, 관련 gate는 `scripts/dev/audit_sdd_build_ast.py`와 `04_verify` summary로 관리한다.

package/sdd/README.md

@@ -0,0 +1,21 @@
+# SDD Governance
+
+## Purpose
+
+- `sdd/`는 템플릿 레포의 canonical delivery system이다.
+- 모든 SDD 산출물은 현재 기준의 최종 일관성만 설명한다.
+
+## Final-Only Rule
+
+- `sdd/` 안에는 날짜별 히스토리, archive, release log, gate log 같은 누적 기록을 두지 않는다.
+- 같은 대상의 후속 작업은 새 문서를 만들지 않고 기존 durable 문서를 덮어써 갱신한다.
+- raw runtime log, backend log, infrastructure log는 SDD가 아니라 해당 운영 시스템의 역할이다.
+
+## Section Map
+
+- `01_planning/`: 현재 canonical spec과 source reference
+- `02_plan/`: 에이전트의 current executable plan
+- `03_build/`: 현재 구현 요약
+- `04_verify/`: 현재 retained verification summary
+- `05_operate/`: 현재 delivery status와 runbook
+- `99_toolchain/`: SDD를 유지하는 생성기, 자동화, 정책 문서

package/server/.dockerignore

@@ -0,0 +1,4 @@
+.venv
+__pycache__
+.pytest_cache
+.env

package/server/.env.example

@@ -0,0 +1,19 @@
+APP_NAME=Template Server
+ENVIRONMENT=development
+API_PREFIX=/api/v1
+CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:3001,http://127.0.0.1:3001,http://localhost:3002,http://127.0.0.1:3002,http://localhost:4000,http://127.0.0.1:4000
+DATABASE_BACKEND=postgres
+POSTGRES_URL=postgresql+psycopg://template:template@postgres:5432/template
+MYSQL_URL=mysql+pymysql://template:template@mysql:3306/template
+MARIADB_URL=mysql+pymysql://template:template@mariadb:3306/template
+MONGODB_URL=mongodb://mongo:27017
+MONGODB_DATABASE=template
+JWT_SECRET=change-me
+JWT_ALGORITHM=HS256
+ACCESS_TOKEN_TTL_MINUTES=120
+BOOTSTRAP_ADMIN_EMAIL=admin@example.com
+BOOTSTRAP_ADMIN_PASSWORD=<CHANGE_ME>
+BOOTSTRAP_ADMIN_NAME=Template Admin
+BOOTSTRAP_OPERATOR_EMAIL=operator@example.com
+BOOTSTRAP_OPERATOR_PASSWORD=<CHANGE_ME>
+BOOTSTRAP_OPERATOR_NAME=Template Operator

package/server/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY api ./api
+COPY contexts ./contexts
+COPY shared ./shared
+COPY data ./data
+COPY config.py ./config.py
+COPY main.py ./main.py
+COPY tests ./tests
+COPY .env.example ./.env.example
+
+RUN pip install --no-cache-dir -e ".[dev]"
+
+EXPOSE 8000
+
+CMD ["uvicorn", "api.http.app:app", "--host", "0.0.0.0", "--port", "8000"]

package/server/Dockerfile.dev

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /app
+
+COPY server /app/server
+
+RUN python -m pip install --no-cache-dir --upgrade pip && \
+    python -m pip install --no-cache-dir -e "/app/server[dev]" && \
+    chmod +x /app/server/docker-entrypoint.sh
+
+WORKDIR /app/server
+
+EXPOSE 8000
+
+CMD ["bash", "/app/server/docker-entrypoint.sh"]

package/server/README.md

@@ -0,0 +1,33 @@
+# server
+
+hexagonal/DDD 구조를 따르는 HTTP 서버 보일러플레이트다.
+
+포함 패턴:
+
+- `api/http`, `contexts`, `data`, `tests` root layout
+- `contexts/*/(application|domain|infrastructure|contracts)` 중심 DDD 분리
+- `contexts/auth`, `contexts/user`, `contexts/shipping`, `contexts/alerts` 예시 도메인과 실제 호출 가능한 sample logic
+- HTTP 계약은 `contexts/*/contracts/http`에 둔다
+- `shared/(application|infrastructure)` 공통 레이어
+- `memory`, `postgres`, `mysql`, `mariadb`, `mongodb` adapter 선택 가능
+- `api/http/app.py` FastAPI app entrypoint
+- `config.py` settings cache
+- `api/http/router.py` 중심의 HTTP router aggregation
+- `/health`와 `/api/v1/*` 기본 계약
+- `.env.example`와 pytest 기본 테스트
+
+시작:
+
+```bash
+uv sync --extra dev
+uv run uvicorn api.http.app:app --reload
+```
+
+기본 인증 예시:
+
+- `POST /api/v1/auth/login`
+- `GET /api/v1/auth/me`
+- `GET /api/v1/users`
+- `GET /api/v1/users/{user_id}`
+- `GET /api/v1/shipping/overview`
+- `GET /api/v1/alerts`

package/server/api/__init__.py

@@ -0,0 +1 @@
+__all__ = ["http"]

package/server/api/http/__init__.py

@@ -0,0 +1,4 @@
+from .app import app
+from .router import api_router
+
+__all__ = ["app", "api_router"]

package/server/api/http/app.py

@@ -0,0 +1,53 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from api.http.router import api_router
+from config import get_settings
+from contexts.alerts.application import prepare_alert_store
+from contexts.auth.application import prepare_auth_store
+from contexts.catalog.application import prepare_catalog_store
+from contexts.fulfillment.application import prepare_fulfillment_store
+from contexts.inventory.application import prepare_inventory_store
+from contexts.orders.application import prepare_order_store
+from contexts.shipping.application import prepare_shipping_store
+from contexts.support.application import prepare_support_store
+from contexts.user.application import prepare_user_store
+from shared.application import health_response
+
+settings = get_settings()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    prepare_alert_store()
+    prepare_auth_store()
+    prepare_catalog_store()
+    prepare_fulfillment_store()
+    prepare_inventory_store()
+    prepare_order_store()
+    prepare_shipping_store()
+    prepare_support_store()
+    prepare_user_store()
+    yield
+
+
+app = FastAPI(title=settings.app_name, version="0.1.0", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return health_response()
+
+
+app.include_router(api_router, prefix=settings.api_prefix)

package/server/api/http/router.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter
+
+from contexts.alerts.contracts.http.router import router as alerts_router
+from contexts.auth.contracts.http.router import router as auth_router
+from contexts.catalog.contracts.http.router import router as catalog_router
+from contexts.fulfillment.contracts.http.router import router as fulfillment_router
+from contexts.health.contracts.http.router import router as health_router
+from contexts.inventory.contracts.http.router import router as inventory_router
+from contexts.orders.contracts.http.router import router as orders_router
+from contexts.shipping.contracts.http.router import router as shipping_router
+from contexts.support.contracts.http.router import router as support_router
+from contexts.user.contracts.http.router import router as user_router
+
+api_router = APIRouter()
+api_router.include_router(alerts_router)
+api_router.include_router(auth_router)
+api_router.include_router(catalog_router)
+api_router.include_router(fulfillment_router)
+api_router.include_router(health_router)
+api_router.include_router(inventory_router)
+api_router.include_router(orders_router)
+api_router.include_router(shipping_router)
+api_router.include_router(support_router)
+api_router.include_router(user_router)

package/server/config.py

@@ -0,0 +1,52 @@
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    app_name: str = "Template Server"
+    environment: str = "development"
+    api_prefix: str = "/api/v1"
+    database_backend: Literal["memory", "postgres", "mysql", "mariadb", "mongodb"] = "memory"
+    postgres_url: str = "postgresql+psycopg://template:template@postgres:5432/template"
+    mysql_url: str = "mysql+pymysql://template:template@mysql:3306/template"
+    mariadb_url: str = "mysql+pymysql://template:template@mariadb:3306/template"
+    mongodb_url: str = "mongodb://mongo:27017"
+    mongodb_database: str = "template"
+    jwt_secret: str = "change-me"
+    jwt_algorithm: str = "HS256"
+    access_token_ttl_minutes: int = 120
+    bootstrap_admin_email: str = "admin@example.com"
+    bootstrap_admin_password: str = "<CHANGE_ME>"
+    bootstrap_admin_name: str = "Template Admin"
+    bootstrap_operator_email: str = "operator@example.com"
+    bootstrap_operator_password: str = "<CHANGE_ME>"
+    bootstrap_operator_name: str = "Template Operator"
+    cors_origins: list[str] = Field(
+        default_factory=lambda: [
+            "http://localhost:3000",
+            "http://127.0.0.1:3000",
+            "http://localhost:3001",
+            "http://127.0.0.1:3001",
+            "http://localhost:3002",
+            "http://127.0.0.1:3002",
+            "http://localhost:4000",
+            "http://127.0.0.1:4000",
+        ]
+    )
+
+    @field_validator("cors_origins", mode="before")
+    @classmethod
+    def parse_cors_origins(cls, value: str | list[str]) -> list[str]:
+        if isinstance(value, str):
+            return [item.strip() for item in value.split(",") if item.strip()]
+        return value
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

package/server/contexts/__init__.py

@@ -0,0 +1,12 @@
+__all__ = [
+    "alerts",
+    "auth",
+    "catalog",
+    "fulfillment",
+    "health",
+    "inventory",
+    "orders",
+    "shipping",
+    "support",
+    "user",
+]

package/server/contexts/alerts/__init__.py

@@ -0,0 +1 @@
+__all__ = ["application", "contracts", "domain", "infrastructure"]

package/server/contexts/alerts/application/__init__.py

@@ -0,0 +1,13 @@
+from .services import (
+    get_alerts,
+    mark_alert_read,
+    mark_all_alerts_read,
+    prepare_alert_store,
+)
+
+__all__ = [
+    "get_alerts",
+    "mark_alert_read",
+    "mark_all_alerts_read",
+    "prepare_alert_store",
+]

package/server/contexts/alerts/application/services.py

@@ -0,0 +1,41 @@
+from contexts.alerts.domain import (
+    AlertItem,
+    AlertReadResult,
+    AlertsPayload,
+    AlertsReadAllResult,
+)
+from contexts.alerts.infrastructure import (
+    list_seed_alerts,
+    mark_all_seed_alerts_read,
+    mark_seed_alert_read,
+)
+
+
+def _to_alert_item(record: AlertItem) -> AlertItem:
+    return AlertItem(**record.model_dump())
+
+
+def get_alerts() -> AlertsPayload:
+    records = list_seed_alerts()
+    return AlertsPayload(
+        unread_count=sum(1 for record in records if not record.read),
+        items=[_to_alert_item(record) for record in records],
+    )
+
+
+def mark_alert_read(alert_id: str) -> AlertReadResult:
+    record = mark_seed_alert_read(alert_id)
+    return AlertReadResult(**record.model_dump())
+
+
+def mark_all_alerts_read() -> AlertsReadAllResult:
+    updated_count = mark_all_seed_alerts_read()
+    unread_count = sum(1 for record in list_seed_alerts() if not record.read)
+    return AlertsReadAllResult(
+        updated_count=updated_count,
+        unread_count=unread_count,
+    )
+
+
+def prepare_alert_store() -> None:
+    list_seed_alerts()

package/server/contexts/alerts/contracts/__init__.py

@@ -0,0 +1,3 @@
+from .http.router import router
+
+__all__ = ["router"]

package/server/contexts/alerts/contracts/http/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/server/contexts/alerts/contracts/http/router.py

@@ -0,0 +1,37 @@
+from fastapi import APIRouter, Depends, HTTPException
+
+from contexts.alerts.application import (
+    get_alerts,
+    mark_alert_read,
+    mark_all_alerts_read,
+)
+from contexts.alerts.domain import (
+    AlertReadResult,
+    AlertsPayload,
+    AlertsReadAllResult,
+)
+from contexts.auth.contracts.http.dependencies import require_admin_user
+
+router = APIRouter(
+    prefix="/alerts",
+    tags=["alerts"],
+    dependencies=[Depends(require_admin_user)],
+)
+
+
+@router.get("", response_model=AlertsPayload)
+def list_alerts() -> AlertsPayload:
+    return get_alerts()
+
+
+@router.post("/read-all", response_model=AlertsReadAllResult)
+def read_all_alerts() -> AlertsReadAllResult:
+    return mark_all_alerts_read()
+
+
+@router.post("/{alert_id}/read", response_model=AlertReadResult)
+def read_alert(alert_id: str) -> AlertReadResult:
+    try:
+        return mark_alert_read(alert_id)
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc

package/server/contexts/alerts/domain/__init__.py

@@ -0,0 +1,15 @@
+from .models import (
+    AlertItem,
+    AlertReadResult,
+    AlertRecord,
+    AlertsPayload,
+    AlertsReadAllResult,
+)
+
+__all__ = [
+    "AlertItem",
+    "AlertReadResult",
+    "AlertRecord",
+    "AlertsPayload",
+    "AlertsReadAllResult",
+]