docs(adr): record domain-first modular monolith

Author: dev-wooyeon

AGENTS.md

@@ -6,14 +6,15 @@
 - 현재 MDX 파이프라인을 보존한다. MDX는 `next.config.mjs`의 `@mdx-js/loader`
   기반 커스텀 webpack rule에 남겨둔다. 전체 콘텐츠 파이프라인을 의도적으로
   마이그레이션하지 않는 한 Next.js 내장 MDX로 바꾸지 않는다.
-- 시각화 중심 UI는 `src/components/visualization/`에 둔다. 명확한
-  아키텍처 이유 없이 다른 폴더로 옮기지 않는다.
+- 시각화 중심 UI는 `shared/visualization/`에 둔다. 블로그 MDX가 재사용하는
+  시각화 컴포넌트는 도메인 코드가 아니라 shared 시각화 모듈로 관리한다.
 - `any`를 사용하지 않는다. 구체 타입을 쓰거나 `unknown`과 narrowing을
   사용한다.
 - `p-[13px]` 같은 arbitrary Tailwind value를 사용하지 않는다. 표준 utility,
   shared token, 기존 스타일 패턴을 사용한다.
-- feature-first 구조를 flat shared folder 구조로 바꾸지 않는다.
-  `src/features/`, `src/shared/`, `src/domains/`를 책임별로 유지한다.
+- DDD의 전략적 설계 개념을 차용한 domain-first modular monolith 구조를
+  유지한다. 주요 도메인은 `src`와 같은 최상위 모듈로 분리하고, `src/app`은
+  Next.js route adapter로 제한한다.
 - 블로그 콘텐츠 구조는 `posts/**/index.mdx`와 주변 `meta.json`으로 유지한다.
   중첩된 series 디렉터리도 보존한다.
 - 변경이 아래 ADR 작성 조건에 걸리면 반드시 ADR을 작성하거나 갱신한다.
@@ -38,16 +39,20 @@ ADR 작성 기준:
 
 ## 프로젝트 구조
 
-- `src/app/`: Next.js App Router 페이지, 레이아웃, 핸들러
-- `src/core/`: 앱 수준 provider와 설정 조합
-- `src/domains/`: feature 사이에서 공유되는 계약과 스키마
-- `src/features/`: blog, home, resume, search 같은 feature 모듈
-- `src/shared/`: 재사용 가능한 UI, layout, analytics, SEO, provider
-- `src/components/visualization/`: animation과 시각화 중심 컴포넌트
-- `src/styles/`: design token과 global style
+- `src/app/`: Next.js App Router route adapter, route handler, metadata entry
+- `blog/`: 글 도메인. post schema, repository, publication policy, series,
+  blog UI, view-count use case
+- `resume/`: 이력서 도메인. resume data, ordering, resume UI
+- `search/`: 검색 도메인. command palette, search action, recommendation
+- `site/`: 도메인 조합 layer. home, AppShell, navigation, provider, site config
+- `platform/`: 외부/런타임 인프라. Supabase, Umami analytics, SEO helper,
+  devtool integration
+- `shared/`: 도메인 지식 없는 UI primitive, motion helper, testing helper,
+  visualization widget
+- `styles/`: design token과 global style
 - `posts/`: 중첩 가능한 `index.mdx`와 `meta.json` 기반 블로그 콘텐츠
 - `tests/`: Playwright E2E 테스트
-- `internal/`: script와 tool configuration
+- `tooling/`: script와 tool configuration
 
 ## 개발 명령
 

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ARCHITECTURE
 
-Last updated: 2026-05-06
+Last updated: 2026-05-07
 
 ## System Summary
 
@@ -21,7 +21,7 @@ Last updated: 2026-05-06
 - Rendering mix:
   - Static prerendered route params via `generateStaticParams` for post pages.
   - Server route handlers for feed and OG image.
-  - Server actions for view counting.
+  - Domain-owned server actions for view counting.
 
 ### Edge Runtime
 
@@ -40,12 +40,12 @@ Last updated: 2026-05-06
 - Route handlers:
   - `/feed.xml` (`src/app/feed.xml/route.ts`)
   - `/api/og` (`src/app/api/og/route.tsx`)
-- Server action:
-  - `src/app/actions/view.ts` for increment/read view count.
+- `src/app` imports page adapters from top-level domain modules and does not own
+  domain policy.
 
-### Content Layer (`posts/**` + `src/features/blog/services`)
+### Content Layer (`posts/**` + `blog/services`)
 
-- `src/features/blog/services/post-repository.ts` recursively discovers valid post folders (`index.mdx` + `meta.json`).
+- `blog/services/post-repository.ts` recursively discovers valid post folders (`index.mdx` + `meta.json`).
 - `meta.json` is validated with Zod (`FeedFrontmatterSchema`).
 - MDX is loaded by dynamic import per folder path.
 - Reading time is auto-derived from MDX when metadata omits it.
@@ -57,31 +57,32 @@ Last updated: 2026-05-06
   - `remark-gfm`
   - `rehype-slug`
   - `rehype-pretty-code`
-- `src/features/blog/services/markdown-parser.ts` parses MDX headings for TOC data.
-- `src/features/blog/ui/mdx/components.tsx` maps MDX nodes to UI components and interactive visualization widgets.
+- `blog/services/markdown-parser.ts` parses MDX headings for TOC data.
+- `blog/ui/mdx/components.tsx` maps MDX nodes to UI components and interactive visualization widgets.
 
-### Feature/Shared Layer (`src/features` + `src/shared` + `src/styles`)
+### Domain-first Modular Monolith
 
-- Feature-first organization:
-  - `src/features/blog`, `src/features/resume`, `src/features/search`, `src/features/home`
-  - `src/shared/analytics`, `src/shared/layout`, `src/shared/ui`, `src/shared/providers`, `src/shared/seo`
-  - `src/components/visualization` is intentionally preserved for heavy visualization widgets.
-- Design tokens in `src/styles/tokens.css`.
-- Global base styles and typography in `src/styles/globals.css`.
-- Theming via `next-themes` provider.
+- `blog/`: post schema, repository, publication policy, series, blog UI, view-count use case.
+- `resume/`: resume data, ordering, resume UI.
+- `search/`: command palette, search action, search recommendation.
+- `site/`: home composition, AppShell, navigation, providers, site config.
+- `platform/`: Supabase integration, Umami analytics, SEO helper, devtools.
+- `shared/`: domain-agnostic UI, layout primitive, motion helper, testing helper, visualization widget.
+- `styles/`: design tokens, global base styles, local font CSS.
+- Theming via `next-themes` provider in `site/providers`.
 
 ### Data and Integrations
 
-- Supabase client setup in `src/shared/integrations/supabase.ts`.
+- Supabase client setup in `platform/integrations/supabase.ts`.
 - View count data model:
   - table: `public.views`
   - rpc: `increment_view(slug_input text) -> bigint`
 - SQL provisioning script: `docs/database/supabase-view-count.sql`.
 
 ### Analytics and SEO
 
-- Umami event helpers in `src/shared/analytics/lib/analytics.ts`.
-- Trackers in `src/shared/analytics/components/*`.
+- Umami event helpers in `platform/analytics/lib/analytics.ts`.
+- Trackers in `platform/analytics/components/*`.
 - Structured data via `JsonLd` component in layout and post page.
 
 ## Request/Data Flows
@@ -92,7 +93,7 @@ Last updated: 2026-05-06
 2. Request to `/blog/[slug]` resolves post via `getFeedData(slug)`.
 3. MDX source is parsed for heading structure (TOC).
 4. MDX component renders with mapped custom components.
-5. Client tracker records post view; server action can persist counter in Supabase.
+5. Client tracker records post view; `blog/api/view.ts` can persist counter in Supabase.
 
 ### Feed Flow
 
@@ -109,19 +110,20 @@ Last updated: 2026-05-06
 
 ## Testing and Quality
 
-- Unit/component tests: Vitest + Testing Library (`src/**/*.test.ts(x)`).
+- Unit/component tests: Vitest + Testing Library across top-level modules and `src/app`.
 - E2E tests: Playwright mobile-focused projects (`tests/e2e/**/*.spec.ts`).
 - Linting/formatting: ESLint, Prettier, markdownlint, cspell.
-- Coverage focus includes `src/features`, `src/shared`, `src/styles`, and selected route domains.
+- Coverage focus includes `blog`, `resume`, `search`, `site`, `platform`,
+  `shared`, `styles`, and selected route adapters.
 
 ## Current Architecture Risks
 
 1. Docs/runtime drift:
    - AGENTS and README mention older stack assumptions; package versions are newer.
 2. Provider boundary drift:
    - Route/layout changes can reintroduce duplicated tracker mounts if `AppProviders` is bypassed.
-3. Content/animation docs drift:
-   - Documented `src/components/animations` path does not exist in current tree.
+3. Boundary enforcement drift:
+   - Module boundaries are physical and documented, but lint-level enforcement is not yet configured.
 4. SEO endpoint mismatch risk:
    - Post JSON-LD image URL differs from the actual OG route path/domain conventions.
 
@@ -134,3 +136,4 @@ Last updated: 2026-05-06
 3. Keep token-first styling and avoid one-off visual constants where possible.
 4. Keep route-level separation for feed, OG, and view-count concerns.
 5. Keep Umami analytics separate from Supabase-backed public view counts.
+6. Keep top-level domain modules as documented in ADR 0011.

README.md

@@ -75,23 +75,19 @@
 ```text
 eunu.log/
 ├── 📁 src/
-│   ├── 📁 app/                 # 라우트 엔트리 전용 (Next App Router)
-│   ├── 📁 core/                # 앱 전역 설정/프로바이더 조합
-│   ├── 📁 domains/             # 도메인 계약/타입/스키마
-│   ├── 📁 features/            # 기능 모듈(ui/model/services)
-│   │   ├── 📁 blog/
-│   │   ├── 📁 resume/
-│   │   ├── 📁 search/
-│   │   └── 📁 home/
-│   ├── 📁 shared/              # 공용 모듈(analytics/integrations/layout/seo/testing/ui/types)
-│   ├── 📁 components/
-│   │   └── 📁 visualization/   # 인터랙티브 알고리즘 시각화 전용
-│   └── 📁 styles/              # 전역 스타일과 토큰
+│   └── 📁 app/                 # Next.js route adapter
+├── 📁 blog/                    # 글 도메인
+├── 📁 resume/                  # 이력서 도메인
+├── 📁 search/                  # 검색 도메인
+├── 📁 site/                    # 홈, AppShell, provider, site config
+├── 📁 platform/                # Supabase, Umami, SEO, devtool integration
+├── 📁 shared/                  # 도메인 지식 없는 UI/모션/테스트/시각화
+├── 📁 styles/                  # 전역 스타일과 토큰
 ├── 📁 tests/
 │   └── 📁 e2e/                 # Playwright E2E 테스트
-├── 📁 internal/
-│   ├── 📁 config/              # 내부 lint/spell 설정
-│   └── 📁 scripts/             # 내부 자동화/유틸 스크립트
+├── 📁 tooling/
+│   ├── 📁 config/              # lint/spell 설정
+│   └── 📁 scripts/             # 자동화/유틸 스크립트
 ├── 📁 posts/                   # 블로그 글(MDX + 메타데이터)
 │   └── 📁 [slug]/              # 글 단위 폴더
 │       ├── index.mdx           # 글 본문

docs/DESIGN.md

@@ -1,12 +1,12 @@
 # DESIGN
 
-Last updated: 2026-02-26
+Last updated: 2026-05-07
 
 ## Source of Truth
 
-1. Tokens: `src/styles/tokens.css`
-2. Global style behavior: `src/styles/globals.css`
-3. Reusable component patterns: `src/shared/ui/**`, `src/shared/layout/**`
+1. Tokens: `styles/tokens.css`
+2. Global style behavior: `styles/globals.css`
+3. Reusable component patterns: `shared/ui/**`, `shared/layout/**`
 
 ## Design Guardrails
 

docs/FRONTEND.md

@@ -1,6 +1,6 @@
 # FRONTEND
 
-Last updated: 2026-02-27
+Last updated: 2026-05-07
 
 ## Stack
 
@@ -11,17 +11,19 @@ Last updated: 2026-02-27
 
 ## Frontend Architecture
 
-1. Route layer: `src/app/**`
-2. Feature layer: `src/features/**`
-3. Shared layer: `src/shared/**` (+ visualization: `src/components/visualization/**`)
-4. Styles/tokens: `src/styles/**`
+1. Route adapter layer: `src/app/**`
+2. Domain modules: `blog/**`, `resume/**`, `search/**`
+3. Composition layer: `site/**`
+4. Runtime/integration layer: `platform/**`
+5. Domain-agnostic primitives: `shared/**`
+6. Styles/tokens: `styles/**`
 
 ## Frontend Rules
 
-1. Keep boundaries clear between feature modules (`blog`, `resume`, `search`, `home`) and shared modules (`layout`, `ui`, `analytics`, `providers`, `seo`).
+1. Keep boundaries clear between domain modules (`blog`, `resume`, `search`) and composition/infrastructure modules (`site`, `platform`, `shared`).
 2. Avoid duplicated global trackers/providers in root layout.
-3. Use typed contracts from `src/domains/**/model/types.ts` and `src/shared/types/*`.
-4. Keep MDX custom component mappings centralized in `src/features/blog/ui/mdx/components.tsx`.
+3. Keep domain contracts inside the owning domain module, for example `blog/model/types.ts`.
+4. Keep MDX custom component mappings centralized in `blog/ui/mdx/components.tsx`.
 
 ## Test Expectations
 

docs/README.md

@@ -1,10 +1,12 @@
 # Docs Index
 
-Last updated: 2026-04-17
+Last updated: 2026-05-07
 
-This index tracks the active documentation that should stay aligned with the
-current codebase. If a document is missing here, add it when the document
-becomes part of the maintained workflow.
+This index tracks the smallest set of documentation that must stay aligned with
+the current codebase. It is not a full file inventory.
+
+Prefer updating an existing ADR, guide, exec plan, or README before adding a new
+standalone document.
 
 ## Repository-Level Docs
 
@@ -13,33 +15,19 @@ becomes part of the maintained workflow.
 
 ## Active Documentation
 
-- Engineering baseline:
-  - `docs/FRONTEND.md`
-  - `docs/DESIGN.md`
-  - `docs/RELIABILITY.md`
-  - `docs/SECURITY.md`
-  - `docs/QUALITY_SCORE.md`
-  - `docs/blog-quality-guide.md`
-- Delivery/process:
+- Decisions:
   - `docs/adr/README.md`
+  - `docs/adr/*.md`
+- Planning:
   - `docs/PLANS.md`
   - `docs/exec-plans/active/README.md`
-  - `docs/exec-plans/completed/README.md`
   - `docs/exec-plans/tech-debt-tracker.md`
-  - `docs/guides/agentation-workflow.md`
-  - `docs/guides/pr-workflow.md`
-  - `docs/guides/testing-guide.md`
-  - `docs/guides/ui-components-guide.md`
-- Product/domain:
-  - `docs/PRODUCT_SENSE.md`
-  - `docs/product-specs/index.md`
-  - `docs/product-specs/new-user-onboarding.md`
-  - `docs/design-docs/index.md`
-  - `docs/design-docs/core-beliefs.md`
-- Data/analytics:
-  - `docs/analytics/analytics-kpi-weekly-template.md`
-  - `docs/database/db-schema.md`
-  - `docs/database/supabase-view-count.sql`
+- Maintained guides:
+  - `docs/guides/**`
+- Domain references:
+  - `docs/database/**`
+  - `docs/product-specs/**`
+  - `docs/design-docs/**`
 
 ## Reference / Research
 
@@ -56,6 +44,7 @@ becomes part of the maintained workflow.
 
 1. Use repository-relative paths only in docs (no absolute local paths).
 2. Update `Last updated` when editing policy/process docs.
-3. Move stale auto-generated reports to `docs/archive/` instead of deleting context.
-4. Keep commands copy-pastable from repository root.
-5. Remove or replace stale links when a referenced file no longer exists.
+3. Treat this file as a maintained-doc boundary, not a complete docs inventory.
+4. Move stale auto-generated reports to `docs/archive/` instead of deleting context.
+5. Keep commands copy-pastable from repository root.
+6. Remove or replace stale links when a referenced file no longer exists.

docs/adr/0004-preserve-feature-first-source-structure.md

@@ -1,7 +1,7 @@
 # 0004. Feature-first 소스 구조를 유지한다
 
 Date: 2026-02-28
-Status: Accepted
+Status: Superseded by [0011](0011-adopt-frontend-modular-monolith.md)
 
 ## 배경
 

docs/adr/0005-use-token-first-tailwind-styling.md

@@ -1,7 +1,10 @@
 # 0005. Token-first Tailwind 스타일링을 사용한다
 
 Date: 2026-01-27
-Status: Accepted
+Status: Accepted, path amended by [0011](0011-adopt-frontend-modular-monolith.md)
+
+Note: ADR 0011 moves the physical style path from `src/styles/**` to `styles/**`
+while preserving the token-first styling decision.
 
 ## 배경
 

docs/adr/0006-isolate-visualization-heavy-components.md

@@ -1,7 +1,11 @@
 # 0006. 시각화 중심 컴포넌트를 격리한다
 
 Date: 2026-01-28
-Status: Accepted
+Status: Accepted, path amended by [0011](0011-adopt-frontend-modular-monolith.md)
+
+Note: ADR 0011 moves the physical visualization path from
+`src/components/visualization/**` to `shared/visualization/**` while preserving
+the isolation decision.
 
 ## 배경
 

docs/adr/0009-use-app-shell-for-primary-navigation.md

@@ -1,7 +1,11 @@
 # 0009. 주요 탐색에 AppShell을 사용한다
 
 Date: 2026-04-21
-Status: Accepted
+Status: Accepted, path amended by [0011](0011-adopt-frontend-modular-monolith.md)
+
+Note: ADR 0011 moves AppShell from `src/shared/layout/AppShell/**` to
+`site/shell/AppShell/**` while preserving the single app-shell navigation
+decision.
 
 ## 배경