From e548b3df49c3a61fa8bbec160c725d71d595491f Mon Sep 17 00:00:00 2001
From: bnbong <bbbong9@gmail.com>
Date: Wed, 6 May 2026 13:12:33 +0900
Subject: [PATCH 1/2] [DOCS] add starter selection guide & update fastkit
 output demos

---
 README.md                                     |  11 +-
 docs/en/index.md                              | 104 ++++++----
 docs/en/user-guide/choosing-a-starter.md      | 194 ++++++++++++++++++
 docs/en/user-guide/quick-start.md             |   7 +
 docs/ko/index.md                              | 121 ++++++-----
 mkdocs.yml                                    |   1 +
 .../fastapi-empty/README.md-tpl               |   4 +-
 7 files changed, 337 insertions(+), 105 deletions(-)
 create mode 100644 docs/en/user-guide/choosing-a-starter.md

diff --git a/README.md b/README.md
index 6c9c36b..825a385 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,7 @@ fastkit init --interactive
 ```
 - What it does: Guided step-by-step project setup with intelligent feature selection
 - Features:
+  - **Architecture preset**: `minimal` | `single-module` | `classic-layered` | `domain-starter` (default)
   - **Database selection**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
   - **Authentication**: JWT, OAuth2, FastAPI-Users, Session-based
   - **Background tasks**: Celery, Dramatiq
@@ -77,10 +78,10 @@ fastkit init --interactive
   - **Deployment**: Docker, docker-compose with auto-generated configs
   - **Package manager**: pip, uv, pdm, poetry
   - **Custom packages**: Add your own dependencies
-- Auto-generates:
-  - `main.py` with selected features integrated
-  - Database and authentication configuration files
-  - Docker deployment files (Dockerfile, docker-compose.yml)
+- Auto-generates (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+  - `main.py` regenerated from selected features for `minimal` / `single-module`; preserved as-shipped for `classic-layered` / `domain-starter`
+  - Database and authentication configuration files at preset-specific paths
+  - Docker deployment files (`Dockerfile`, `docker-compose.yml`) with the preset's correct uvicorn entrypoint
   - Test configuration (pytest with coverage)
 
 ### Create a project from a template
@@ -121,9 +122,11 @@ fastkit deleteproject <project_name>
 
 For comprehensive guides and detailed usage instructions, visit our documentation:
 
+- 🧭 **[Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/)** - Beginner decision guide for `startdemo` templates and interactive presets
 - 📚 **[User Guide](https://bnbong.github.io/FastAPI-fastkit/user-guide/quick-start/)** - Detailed installation and usage guides
 - 🎯 **[Tutorial](https://bnbong.github.io/FastAPI-fastkit/tutorial/getting-started/)** - Step-by-step tutorials for beginners
 - 📖 **[CLI Reference](https://bnbong.github.io/FastAPI-fastkit/user-guide/cli-reference/)** - Complete command reference
+- 🧱 **[Architecture Preset Matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/)** - Per-preset / per-feature contract for interactive generation
 - 🔍 **[Template Quality Assurance](https://bnbong.github.io/FastAPI-fastkit/reference/template-quality-assurance/)** - Automated testing and quality standards
 
 ## Contributing
diff --git a/docs/en/index.md b/docs/en/index.md
index 47f8381..bbbf39e 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -275,35 +275,54 @@ Select package manager (pip, uv, pdm, poetry): uv
 📝 Custom Packages (optional)
 Enter custom package names (comma-separated, press Enter to skip):
 
-───────────────── Selected Configuration ─────────────────
-Project: my-fullstack-project
-Database: PostgreSQL
-Authentication: JWT
-Background Tasks: Celery
-Caching: Redis
-Monitoring: Prometheus
-Testing: Coverage
-Utilities: CORS
-Deployment: Docker, docker-compose
-Package Manager: uv
-──────────────────────────────────────────────────────────
+📋 Project Configuration Summary
+┌─────────────────────┬───────────────────────────────────────────────────────────────────────────┐
+│ Setting             │ Value                                                                     │
+├─────────────────────┼───────────────────────────────────────────────────────────────────────────┤
+│ Project Name        │ my-fullstack-project                                                      │
+│ Author              │ John Doe                                                                  │
+│ Email               │ john@example.com                                                          │
+│ Description         │ Full-stack FastAPI project with PostgreSQL and JWT                        │
+│ Architecture Preset │ domain-starter — Domain-oriented: src/app/domains/<concept>/ (recommended)│
+│ Database            │ PostgreSQL                                                                │
+│ Authentication      │ JWT                                                                       │
+│ Async Tasks         │ Celery                                                                    │
+│ Caching             │ Redis                                                                     │
+│ Monitoring          │ Prometheus                                                                │
+│ Testing             │ Coverage                                                                  │
+│ Utilities           │ CORS                                                                      │
+│ Package Manager     │ uv                                                                        │
+└─────────────────────┴───────────────────────────────────────────────────────────────────────────┘
+
+Total dependencies to install: 18
 
 Proceed with project creation? [Y/n]: y
 
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Injected metadata into pyproject.toml              │
+╰──────────────────────────────────────────────────────╯
 ╭─────────────────────── Success ───────────────────────╮
-│ ✨ Generated main.py with selected features           │
-╰───────────────────────────────────────────────────────╯
-╭─────────────────────── Success ───────────────────────╮
-│ ✨ Generated database configuration                   │
+│ ✨ Generated dependency file with 18 packages         │
 ╰───────────────────────────────────────────────────────╯
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Preserving template-shipped main.py for preset     │
+│ 'domain-starter'.                                    │
+╰──────────────────────────────────────────────────────╯
 ╭─────────────────────── Success ───────────────────────╮
-│ ✨ Generated authentication configuration             │
+│ ✨ Generated Docker deployment files                  │
 ╰───────────────────────────────────────────────────────╯
-╭─────────────────────── Success ───────────────────────╮
-│ ✨ Generated test configuration                       │
+╭────────────────────── Warning ────────────────────────╮
+│ ⚠ Preset compatibility                               │
+│ fastapi-domain-starter's shipped src/app/main.py is  │
+│ preserved. The selections below need manual wiring   │
+│ there (CORS is already wired — set                   │
+│ BACKEND_CORS_ORIGINS in .env to activate it).        │
+│ Affected selections (packages installed, but no      │
+│ dynamic main.py edits applied for the                │
+│ 'domain-starter' preset): Prometheus                 │
 ╰───────────────────────────────────────────────────────╯
 ╭─────────────────────── Success ───────────────────────╮
-│ ✨ Generated Docker deployment files                  │
+│ ✨ Generated configuration files for selected stack   │
 ╰───────────────────────────────────────────────────────╯
 
 Creating virtual environment...
@@ -312,27 +331,21 @@ Installing dependencies...
 ----> 100%
 
 ╭─────────────────────── Success ───────────────────────╮
-│ ✨ FastAPI project 'my-fullstack-project' created!    │
-│                                                       │
-│ Generated files:                                      │
-│   • main.py (with all selected features)             │
-│   • src/config/database.py                           │
-│   • src/config/auth.py                               │
-│   • tests/conftest.py                                │
-│   • Dockerfile                                       │
-│   • docker-compose.yml                               │
-│   • pyproject.toml / requirements.txt                │
+│ ✨ FastAPI project 'my-fullstack-project' from        │
+│ 'fastapi-domain-starter' has been created!            │
 ╰───────────────────────────────────────────────────────╯
 ```
 
 </div>
 
 The interactive mode provides:
+- **Architecture preset selection** (`minimal` / `single-module` / `classic-layered` / `domain-starter`) that picks the right base template and project layout
 - **Guided selection** for databases, authentication, background tasks, caching, monitoring, and more
-- **Auto-generated code** for selected features (main.py, config files, Docker files)
+- **Auto-generated code** for selected features — varies by preset (regenerated `main.py` for `minimal` / `single-module`; preserve template-shipped `main.py` and overlay config modules for `classic-layered` / `domain-starter`)
+- **Preset-aware Docker generation** — the generated `Dockerfile` `CMD` targets the preset's actual entrypoint (`src.main:app` or `src.app.main:app`)
 - **Smart dependency management** with automatic pip compatibility
-- **Feature validation** to prevent incompatible combinations
-- **Always Empty project** as base for maximum flexibility
+- **Feature validation** with manual-wiring warnings for selections the preset cannot auto-wire
+- **Identity markers** in the generated `pyproject.toml` (description marker + `[tool.fastapi-fastkit]` table) so `is_fastkit_project()` can recognize generated projects later
 
 ### Add a new route to the FastAPI project
 
@@ -434,18 +447,19 @@ To view the list of available FastAPI demos, check with:
 
 ```console
 $ fastkit list-templates
-                      Available Templates
-┌─────────────────────────┬───────────────────────────────────┐
-│ fastapi-custom-response │ Async Item Management API with    │
-│                         │ Custom Response System            │
-│ fastapi-dockerized      │ Dockerized FastAPI Item           │
-│                         │ Management API                    │
-│ fastapi-empty           │ No description                    │
-│ fastapi-async-crud      │ Async Item Management API Server  │
-│ fastapi-psql-orm        │ Dockerized FastAPI Item           │
-│                         │ Management API with PostgreSQL    │
-│ fastapi-default         │ Simple FastAPI Project            │
-└─────────────────────────┴───────────────────────────────────┘
+                              Available Templates
+┌────────────────────────┬───────────────────────────────────────────────────────┐
+│ fastapi-custom-response│ Async Item Management API with Custom Response System │
+│ fastapi-mcp            │ FastAPI MCP Project                                   │
+│ fastapi-domain-starter │ FastAPI Domain Starter                                │
+│ fastapi-dockerized     │ Dockerized FastAPI Item Management API                │
+│ fastapi-empty          │ Minimal FastAPI Template                              │
+│ fastapi-async-crud     │ Async Item Management API Server                      │
+│ fastapi-psql-orm       │ Dockerized FastAPI Item Management API with           │
+│                        │ PostgreSQL                                            │
+│ fastapi-default        │ Simple FastAPI Project                                │
+│ fastapi-single-module  │ FastAPI Single Module Template                        │
+└────────────────────────┴───────────────────────────────────────────────────────┘
 ```
 
 </div>
diff --git a/docs/en/user-guide/choosing-a-starter.md b/docs/en/user-guide/choosing-a-starter.md
new file mode 100644
index 0000000..003ffae
--- /dev/null
+++ b/docs/en/user-guide/choosing-a-starter.md
@@ -0,0 +1,194 @@
+# Which starter should I choose?
+
+FastAPI-fastkit ships several ways to bootstrap a project. This page is a
+**decision aid** for newcomers: pick a path here, then jump to
+[Quick Start](quick-start.md) to actually create the project.
+
+If you're not sure, the short answer is:
+
+> **Start with `fastkit init --interactive` and pick the
+> `domain-starter` preset.** It's the recommended default for modern API
+> projects.
+
+The rest of this page explains why, and when to pick something else.
+
+## TL;DR — pick by user type
+
+| You are... | Start with |
+|---|---|
+| New to FastAPI, want a guided walkthrough | `fastkit init --interactive` (preset: **`domain-starter`**) |
+| Want a working CRUD demo to read and modify | `fastkit startdemo fastapi-default` |
+| Want the smallest possible scaffold | `fastkit init --interactive` (preset: **`minimal`**) |
+| Writing a quick prototype / single-file script | `fastkit init --interactive` (preset: **`single-module`**) |
+| Need a real database (PostgreSQL + SQLAlchemy + Alembic) | `fastkit startdemo fastapi-psql-orm` |
+| Want production-style domain layout for a medium-sized API | `fastkit init --interactive` (preset: **`domain-starter`**) |
+
+## `startdemo` vs `init --interactive` — what's the difference?
+
+These are the two main entry points. They serve different needs.
+
+### `fastkit startdemo <template>`
+
+Drops a **complete, working example** project onto disk based on one of the
+shipped templates (`fastapi-default`, `fastapi-async-crud`,
+`fastapi-psql-orm`, `fastapi-domain-starter`, ...). The template's source
+code is pasted as-is, with metadata placeholders (`<project_name>`, etc.)
+filled in.
+
+- ✅ Fastest path to a runnable demo.
+- ✅ All code is real and readable — great for learning by example.
+- ❌ The template's stack and structure are fixed; you can't pick CORS but
+  drop authentication on the way in.
+
+```console
+$ fastkit list-templates              # show what's available
+$ fastkit startdemo fastapi-default   # generate a project from one
+```
+
+### `fastkit init --interactive`
+
+Walks you through a **guided wizard**: project metadata → architecture
+preset → feature selections (database, auth, testing, deployment, ...) →
+package manager → confirmation. The generator picks an appropriate base
+template per preset and overlays the features you chose.
+
+- ✅ You assemble the stack you actually want.
+- ✅ The architecture preset shapes the project layout (single-file, layered,
+  domain-oriented, ...).
+- ❌ The richer preserve-main presets (`classic-layered`, `domain-starter`)
+  generate config modules but expect you to wire them into the shipped
+  routers yourself. See the
+  [Architecture Preset Matrix](../reference/preset-feature-matrix.md) for
+  the per-preset / per-feature contract.
+
+```console
+$ fastkit init --interactive
+```
+
+## The four architecture presets
+
+These appear inside `fastkit init --interactive` after the project info
+prompts. Use this section to decide which one to pick.
+
+### `minimal` — start simplest, grow later
+
+Smallest viable FastAPI app. Empty scaffold + a single
+`src/main.py` regenerated from your feature flags. CORS, rate limiting,
+and Prometheus instrumentation are auto-wired into `main.py` if selected.
+
+- 👤 **Who**: people who want to add structure themselves as the project
+  grows, or are exploring FastAPI without preconceived layout opinions.
+- 📦 **Base template**: `fastapi-empty`.
+- 🧠 **Mental model**: "give me one file with FastAPI imported and let me
+  figure out the rest."
+
+### `single-module` — script-style prototype
+
+Everything lives in one module. Same regenerate-`main.py` overlay as
+`minimal`.
+
+- 👤 **Who**: writing a glue script, a small webhook, or a one-day
+  prototype that doesn't need package boundaries.
+- 📦 **Base template**: `fastapi-single-module`.
+- 🧠 **Mental model**: "I want one Python file I can run and read in one
+  sitting."
+
+### `classic-layered` — layered split (api / crud / schemas / core)
+
+The "Django-flavoured" layout — code is split horizontally by concern:
+all routers in `api/`, all CRUD logic in `crud/`, all pydantic schemas in
+`schemas/`, all configuration in `core/`. The shipped `main.py` is
+**preserved** (it already wires CORS for you); generated database/auth
+configs land under `src/core/`.
+
+- 👤 **Who**: teams familiar with Django/Rails-style layouts, projects
+  with many small endpoints sharing common CRUD plumbing.
+- 📦 **Base template**: `fastapi-default`.
+- 🧠 **Mental model**: "split code by what it _is_."
+
+### `domain-starter` — domain-oriented (recommended default)
+
+Code is split vertically by **business concept**: each domain owns its
+own router, service, repository, and schemas under
+`src/app/domains/<concept>/`. Comes with a `/health` endpoint and an
+`items` example domain that you copy and rename for each new concept.
+The shipped `main.py` (under `src/app/`) is preserved; generated configs
+land under `src/app/core/`.
+
+- 👤 **Who**: medium-sized APIs that will grow several distinct concepts
+  (users, orders, billing, ...). The recommended modern default.
+- 📦 **Base template**: `fastapi-domain-starter`.
+- 🧠 **Mental model**: "split code by what it _does_ for the business."
+
+## Comparison matrix
+
+A side-by-side at a glance.
+
+| | `minimal` | `single-module` | `classic-layered` | `domain-starter` |
+|---|---|---|---|---|
+| Base template | `fastapi-empty` | `fastapi-single-module` | `fastapi-default` | `fastapi-domain-starter` |
+| Project entry | `src/main.py` | `src/main.py` | `src/main.py` | `src/app/main.py` |
+| Routers location | (you add) | (inside `main.py`) | `src/api/routes/` | `src/app/domains/<concept>/router.py` |
+| Per-domain folders | ❌ | ❌ | ❌ | ✅ |
+| Built-in `/health` endpoint | ✅ | ✅ | ❌ | ✅ |
+| `main.py` regenerated from features | ✅ | ✅ | ❌ | ❌ |
+| CORS pre-wired in `main.py` | added when selected | added when selected | yes (env-driven) | yes (env-driven) |
+| pyproject-first | optional | optional | optional | ✅ |
+| Best for | "I'll grow my own structure" | "one-file prototype" | "split by concern" | "split by business concept" |
+
+For the full per-feature contract (database / auth config target paths,
+which selections need manual wiring vs auto-wiring, when warnings fire),
+see the [Architecture Preset Matrix](../reference/preset-feature-matrix.md).
+
+## Picking a `startdemo` template
+
+`fastkit startdemo <template>` is best when you want a **complete,
+runnable example** rather than a guided assembly. Most templates roughly
+correspond to one of the four presets above, but they ship with extra
+example code (CRUD endpoints over a mock store, custom response handling,
+Docker tooling, etc.).
+
+| Template | Closest preset | When to pick it |
+|---|---|---|
+| `fastapi-default` | `classic-layered` | Working CRUD demo with the layered layout. Good first stop. |
+| `fastapi-empty` | `minimal` | Bare scaffold; same shape `minimal` lands on. |
+| `fastapi-single-module` | `single-module` | Single-file demo. |
+| `fastapi-domain-starter` | `domain-starter` | Recommended modern default; ships with an items domain example. |
+| `fastapi-async-crud` | `classic-layered` | Async-flavoured equivalent of `fastapi-default`. |
+| `fastapi-custom-response` | `classic-layered` | Demonstrates custom response envelopes / formatting. |
+| `fastapi-dockerized` | `classic-layered` | Adds a production-ready Dockerfile to the default layout. |
+| `fastapi-psql-orm` | (no direct preset) | PostgreSQL + SQLAlchemy + Alembic. Pick this when you need a real database. |
+| `fastapi-mcp` | (no direct preset) | Model Context Protocol integration. |
+
+`fastkit list-templates` shows the live list with one-line descriptions.
+
+## Common questions
+
+**Q. Do I have to pick a preset / template up front?**
+No — you can always reorganize the generated code by hand later. The
+presets are starting points, not contracts. Don't over-think the choice.
+
+**Q. Which is the "modern" choice?**
+`domain-starter`. It's pyproject-first, ships with a `/health` endpoint,
+and uses the layout most well-run mid-sized FastAPI projects converge on.
+
+**Q. Can I switch from `classic-layered` to `domain-starter` later?**
+Yes, but it's a manual refactor — there's no migration command. If you
+think your project will grow enough to need domain folders, start there.
+
+**Q. What if I just want to learn FastAPI?**
+Start with `fastkit startdemo fastapi-default` — read the code, run the
+tests, change a few endpoints. Once you're comfortable, `fastkit init
+--interactive` with the `domain-starter` preset is the natural next step.
+
+**Q. Where do I see the exact files each preset generates?**
+The [Architecture Preset Matrix](../reference/preset-feature-matrix.md)
+is the reference page for that.
+
+## Next steps
+
+- [Quick Start](quick-start.md) — actually create your first project.
+- [Creating Projects](creating-projects.md) — deeper walkthrough of the
+  CLI flags.
+- [Architecture Preset Matrix](../reference/preset-feature-matrix.md) —
+  the full per-preset / per-feature contract.
diff --git a/docs/en/user-guide/quick-start.md b/docs/en/user-guide/quick-start.md
index 63a41fa..3c1ebe2 100644
--- a/docs/en/user-guide/quick-start.md
+++ b/docs/en/user-guide/quick-start.md
@@ -2,6 +2,13 @@
 
 Create your first FastAPI project with FastAPI-fastkit in under 5 minutes!
 
+!!! tip "Not sure which starter to pick?"
+    See [**Which starter should I choose?**](choosing-a-starter.md) for a
+    beginner-friendly comparison of `startdemo` templates and interactive
+    architecture presets (`minimal` / `single-module` / `classic-layered`
+    / `domain-starter`). The short answer: **`fastkit init --interactive`
+    with the `domain-starter` preset is the recommended modern default.**
+
 ## 1. Create Project
 
 Use FastAPI-fastkit's `init` command to create a new project:
diff --git a/docs/ko/index.md b/docs/ko/index.md
index 7219881..c58d0ce 100644
--- a/docs/ko/index.md
+++ b/docs/ko/index.md
@@ -276,36 +276,55 @@ Select monitoring: 3
 📝 사용자 정의 패키지(선택 사항)
 사용자 정의 패키지 이름을 입력하세요(쉼표로 구분, 건너뛰려면 Enter):
 
-───────────────── 선택된 구성 ─────────────────
-프로젝트: my-fullstack-project
-데이터베이스: PostgreSQL
-인증: JWT
-백그라운드 작업: Celery
-캐싱: Redis
-모니터링: Prometheus
-테스트: Coverage
-유틸리티: CORS
-배포: Docker, docker-compose
-패키지 매니저: uv
-──────────────────────────────────────────────────────────
-
-프로젝트 생성을 진행하시겠습니까? [Y/n]: y
+📋 Project Configuration Summary
+┌─────────────────────┬───────────────────────────────────────────────────────────────────────────┐
+│ Setting             │ Value                                                                     │
+├─────────────────────┼───────────────────────────────────────────────────────────────────────────┤
+│ Project Name        │ my-fullstack-project                                                      │
+│ Author              │ John Doe                                                                  │
+│ Email               │ john@example.com                                                          │
+│ Description         │ Full-stack FastAPI project with PostgreSQL and JWT                        │
+│ Architecture Preset │ domain-starter — Domain-oriented: src/app/domains/<concept>/ (recommended)│
+│ Database            │ PostgreSQL                                                                │
+│ Authentication      │ JWT                                                                       │
+│ Async Tasks         │ Celery                                                                    │
+│ Caching             │ Redis                                                                     │
+│ Monitoring          │ Prometheus                                                                │
+│ Testing             │ Coverage                                                                  │
+│ Utilities           │ CORS                                                                      │
+│ Package Manager     │ uv                                                                        │
+└─────────────────────┴───────────────────────────────────────────────────────────────────────────┘
+
+Total dependencies to install: 18
+
+Proceed with project creation? [Y/n]: y
 
-╭─────────────────────── 성공 ───────────────────────╮
-│ ✨ 선택한 기능이 포함된 main.py 생성              │
-╰────────────────────────────────────────────────────╯
-╭─────────────────────── 성공 ───────────────────────╮
-│ ✨ 데이터베이스 구성 생성                          │
-╰────────────────────────────────────────────────────╯
-╭─────────────────────── 성공 ───────────────────────╮
-│ ✨ 인증 구성 생성                                  │
-╰────────────────────────────────────────────────────╯
-╭─────────────────────── 성공 ───────────────────────╮
-│ ✨ 테스트 구성 생성                                │
-╰────────────────────────────────────────────────────╯
-╭─────────────────────── 성공 ───────────────────────╮
-│ ✨ Docker 배포 파일 생성                           │
-╰────────────────────────────────────────────────────╯
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Injected metadata into pyproject.toml              │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Generated dependency file with 18 packages         │
+╰───────────────────────────────────────────────────────╯
+╭──────────────────────── Info ────────────────────────╮
+│ ℹ Preserving template-shipped main.py for preset     │
+│ 'domain-starter'.                                    │
+╰──────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Generated Docker deployment files                  │
+╰───────────────────────────────────────────────────────╯
+╭────────────────────── Warning ────────────────────────╮
+│ ⚠ Preset compatibility                               │
+│ fastapi-domain-starter's shipped src/app/main.py is  │
+│ preserved. The selections below need manual wiring   │
+│ there (CORS is already wired — set                   │
+│ BACKEND_CORS_ORIGINS in .env to activate it).        │
+│ Affected selections (packages installed, but no      │
+│ dynamic main.py edits applied for the                │
+│ 'domain-starter' preset): Prometheus                 │
+╰───────────────────────────────────────────────────────╯
+╭─────────────────────── Success ───────────────────────╮
+│ ✨ Generated configuration files for selected stack   │
+╰───────────────────────────────────────────────────────╯
 
 가상 환경을 생성하는 중...
 종속성을 설치하는 중...
@@ -314,27 +333,20 @@ Select monitoring: 3
 
 ╭─────────────────────── 성공 ───────────────────────╮
 │ ✨ FastAPI 프로젝트 'my-fullstack-project'가       │
-│   생성되었습니다!                                  │
-│                                                    │
-│ 생성된 파일:                                       │
-│   • main.py (선택한 모든 기능 포함)               │
-│   • src/config/database.py                         │
-│   • src/config/auth.py                             │
-│   • tests/conftest.py                              │
-│   • Dockerfile                                     │
-│   • docker-compose.yml                             │
-│   • pyproject.toml / requirements.txt              │
+│   'fastapi-domain-starter' 템플릿에서 생성되었습니다│
 ╰────────────────────────────────────────────────────╯
 ```
 
 </div>
 
 대화형 모드가 제공하는 기능:
+- **아키텍처 프리셋 선택** (`minimal` / `single-module` / `classic-layered` / `domain-starter`) — 베이스 템플릿과 프로젝트 레이아웃을 선택
 - 데이터베이스, 인증, 백그라운드 작업, 캐싱, 모니터링 등 기능에 대한 가이드형 선택
-- 선택한 기능에 대한 자동 코드 생성(main.py, 구성 파일, Docker 파일)
+- 선택한 기능에 대한 자동 코드 생성 — 프리셋에 따라 동작 방식 차이 (`minimal` / `single-module`은 `main.py` 재생성, `classic-layered` / `domain-starter`는 템플릿 제공 `main.py` 보존하며 구성 모듈만 추가)
+- 프리셋에 맞춘 Docker 생성 — 생성된 `Dockerfile`의 `CMD`가 해당 프리셋의 실제 진입점(`src.main:app` 또는 `src.app.main:app`)을 가리킴
 - 자동 pip 호환성의 스마트 종속성 관리
-- 호환되지 않는 조합을 방지하는 기능 검증
-- 최대 유연성을 위한 Always Empty project를 기본 베이스로 제공
+- 호환되지 않는 조합을 방지하는 기능 검증과 수동 와이어링 경고
+- 생성된 `pyproject.toml`에 식별 마커 주입 (`description` 마커 + `[tool.fastapi-fastkit]` 테이블) — 이후 `is_fastkit_project()`가 생성된 프로젝트를 식별 가능
 
 ### FastAPI 프로젝트에 새 라우트를 추가하기
 
@@ -436,18 +448,19 @@ FastAPI 템플릿 프로젝트가 '~your-project-path~'에 배포됩니다
 
 ```console
 $ fastkit list-templates
-                      사용 가능한 템플릿
-┌─────────────────────────┬───────────────────────────────────┐
-│ fastapi-custom-response │ 커스텀 응답 시스템을 갖춘 비동기  │
-│                         │ 아이템 관리 API                   │
-│ fastapi-dockerized      │ Docker로 컨테이너화된 FastAPI     │
-│                         │ 아이템 관리 API                   │
-│ fastapi-empty           │ 설명 없음                         │
-│ fastapi-async-crud      │ 비동기 아이템 관리 API 서버       │
-│ fastapi-psql-orm        │ PostgreSQL을 사용하는 Docker로    │
-│                         │ 컨테이너화된 FastAPI 아이템 관리 API │
-│ fastapi-default         │ 간단한 FastAPI 프로젝트           │
-└─────────────────────────┴───────────────────────────────────┘
+                              Available Templates
+┌────────────────────────┬───────────────────────────────────────────────────────┐
+│ fastapi-custom-response│ Async Item Management API with Custom Response System │
+│ fastapi-mcp            │ FastAPI MCP Project                                   │
+│ fastapi-domain-starter │ FastAPI Domain Starter                                │
+│ fastapi-dockerized     │ Dockerized FastAPI Item Management API                │
+│ fastapi-empty          │ Minimal FastAPI Template                              │
+│ fastapi-async-crud     │ Async Item Management API Server                      │
+│ fastapi-psql-orm       │ Dockerized FastAPI Item Management API with           │
+│                        │ PostgreSQL                                            │
+│ fastapi-default        │ Simple FastAPI Project                                │
+│ fastapi-single-module  │ FastAPI Single Module Template                        │
+└────────────────────────┴───────────────────────────────────────────────────────┘
 ```
 
 </div>
diff --git a/mkdocs.yml b/mkdocs.yml
index 8ad37a8..aebfdc5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -120,6 +120,7 @@ nav:
   - User Guide:
     - Installation: user-guide/installation.md
     - Quick Start: user-guide/quick-start.md
+    - Choosing a Starter: user-guide/choosing-a-starter.md
     - Creating Projects: user-guide/creating-projects.md
     - Adding Routes: user-guide/adding-routes.md
     - Using Templates: user-guide/using-templates.md
diff --git a/src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl b/src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl
index 530ddb3..9f5c46f 100644
--- a/src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl
+++ b/src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl
@@ -1,6 +1,6 @@
-# <project_name>
+# Minimal FastAPI Template
 
-> Minimal FastAPI template for rapid prototyping
+> Generated project: **<project_name>** — minimal FastAPI scaffold for rapid prototyping
 
 A minimal FastAPI template that provides the basic structure for building FastAPI applications. Perfect for getting started quickly or as a foundation for more complex projects.
 

From 64691f2c40194e4300c9eea4eb7bae913333fe55 Mon Sep 17 00:00:00 2001
From: bnbong <bbbong9@gmail.com>
Date: Wed, 6 May 2026 13:49:41 +0900
Subject: [PATCH 2/2] [DOCS] add domain-starter tutorial & translation
 completeness & language status in docs

---
 docs/en/contributing/translation-guide.md     |  29 +-
 docs/en/index.md                              |   7 +
 docs/en/reference/translation-status.md       | 123 +++++
 docs/en/tutorial/domain-starter.md            | 454 ++++++++++++++++++
 docs/en/user-guide/choosing-a-starter.md      |   4 +
 docs/ko/index.md                              |   8 +
 mkdocs.yml                                    |   2 +
 .../fastapi-domain-starter/README.md-tpl      |   4 +
 8 files changed, 630 insertions(+), 1 deletion(-)
 create mode 100644 docs/en/reference/translation-status.md
 create mode 100644 docs/en/tutorial/domain-starter.md

diff --git a/docs/en/contributing/translation-guide.md b/docs/en/contributing/translation-guide.md
index bfcb8e6..d80fcdd 100644
--- a/docs/en/contributing/translation-guide.md
+++ b/docs/en/contributing/translation-guide.md
@@ -2,6 +2,26 @@
 
 This guide explains how to contribute translations for FastAPI-fastkit documentation.
 
+## Source of truth and translation policy
+
+> **English (`en`) is the canonical source of truth** for FastAPI-fastkit
+> documentation. Every other locale is a translation target that may
+> lag behind English by a release or by individual pages.
+>
+> If a translated page disagrees with the English page, **trust the
+> English page** until the translation catches up. Translations are
+> shipped at whatever completeness contributors have reached — partial
+> coverage is normal and expected.
+
+The user-facing companion to this policy is the
+[Translation Status](../reference/translation-status.md) page, which
+lists each locale's actual completeness and how MkDocs renders pages
+that haven't been translated yet (TL;DR: they fall back to English).
+
+When you contribute a translation, also update the status page's table
+so users can tell what's available without guessing from the language
+switcher.
+
 ## Overview
 
 FastAPI-fastkit uses an automated translation system powered by AI to translate documentation into multiple languages. The system:
@@ -11,9 +31,16 @@ FastAPI-fastkit uses an automated translation system powered by AI to translate
 - Saves translations to language-specific directories
 - Creates GitHub Pull Requests for review
 
+The automation produces a starting point; human review is still
+required before merging. AI-generated translations should be flagged as
+"draft" in their PRs and reviewed by a fluent speaker before landing.
+
 ## Supported Languages
 
-Currently supported languages:
+These are the locales the docs site currently **builds**. Build target
+configuration alone does **not** mean a locale's pages are translated —
+see [Translation Status](../reference/translation-status.md) for actual
+per-locale completeness.
 
 - 🇰🇷 Korean (ko)
 - 🇯🇵 Japanese (ja)
diff --git a/docs/en/index.md b/docs/en/index.md
index bbbf39e..f1f75b1 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -22,6 +22,12 @@ This project was created to speed up the configuration of the development enviro
 
 This project was inspired by the `SpringBoot initializer` & Python Django's `django-admin` cli operation.
 
+!!! info "Translation status"
+    English is the source of truth for these docs. Other languages in
+    the language switcher may be partial or fall back to English page by
+    page. See [Translation Status](reference/translation-status.md) for
+    each locale's actual completeness.
+
 ## Key Features
 
 - **⚡ Immediate FastAPI project creation** : Super-fast FastAPI workspace & project creation via CLI, inspired by `django-admin` feature of [Python Django](https://github.com/django/django)
@@ -481,6 +487,7 @@ Learn FastAPI development through practical use cases with our pre-built templat
 
 - **[Building a Basic API Server](tutorial/basic-api-server.md)** - Create your first FastAPI server using the `fastapi-default` template
 - **[Building an Asynchronous CRUD API](tutorial/async-crud-api.md)** - Develop a high-performance async API with the `fastapi-async-crud` template
+- **[Domain-oriented Project (Domain Starter)](tutorial/domain-starter.md)** - Build a medium-sized API with the `fastapi-domain-starter` template, the recommended modern default
 
 ### 🗄️ Database & Infrastructure
 
diff --git a/docs/en/reference/translation-status.md b/docs/en/reference/translation-status.md
new file mode 100644
index 0000000..e5b044d
--- /dev/null
+++ b/docs/en/reference/translation-status.md
@@ -0,0 +1,123 @@
+# Translation status
+
+FastAPI-fastkit ships docs in several languages, but those translations
+are **not at parity**. This page is the single source of truth for what
+is actually translated where, what gets shown when a page hasn't been
+translated, and how to help.
+
+## Source of truth
+
+> **English (`en`) is the source of truth.** All product, CLI, and API
+> behaviour described in the docs is authored against the English files
+> first. Other locales are translations of those English sources and may
+> lag behind a release.
+>
+> If a translated page disagrees with the English page, **trust the
+> English page** until the translation is updated.
+
+The English files live under [`docs/en/`](https://github.com/bnbong/FastAPI-fastkit/tree/main/docs/en).
+Every other locale (`docs/ko/`, `docs/ja/`, ...) is a translation
+target.
+
+## Per-locale completeness
+
+The numbers below count Markdown pages in each locale's directory tree
+relative to the English source. They reflect what's actually present in
+the repository — not what shows up in the language switcher (which the
+next section explains).
+
+| Locale | Status | Markdown pages | Notes |
+|---|---|---:|---|
+| 🇬🇧 English (`en`) | ✅ Source of truth | 26 / 26 | Authoritative. |
+| 🇰🇷 Korean (`ko`) | 🟡 Partial | 2 / 26 | `index.md`, `changelog.md`. Other pages fall back to English. |
+| 🇯🇵 Japanese (`ja`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
+| 🇨🇳 Chinese (`zh`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
+| 🇪🇸 Spanish (`es`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
+| 🇫🇷 French (`fr`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
+| 🇩🇪 German (`de`) | 🔴 Skeleton | 0 / 26 | Build target only. Every page falls back to English. |
+
+*Snapshot verified 2026-05-06.* These counts are maintained by hand;
+to recount the current state from the repo root, run:
+
+```console
+$ for loc in en ko ja zh es fr de; do
+    echo "$loc: $(find docs/$loc -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
+  done
+```
+
+If the recount disagrees with the table, the table is stale — please
+update it (or open a PR / issue noting the drift).
+
+Legend:
+
+- ✅ **Source of truth** — the locale we author against.
+- 🟡 **Partial** — some pages translated; missing pages fall back.
+- 🔴 **Skeleton** — language switcher entry exists, but no translated
+  pages are checked in yet. The site renders English content under the
+  translated nav labels.
+
+## How fallback works
+
+The docs site uses
+[`mkdocs-static-i18n`](https://github.com/ultrabug/mkdocs-static-i18n)
+with `fallback_to_default: true`. This means:
+
+- For each translated locale, MkDocs only writes pages that exist in
+  that locale's directory.
+- For every page **not** present in a locale, the build falls back to
+  the English version of that page.
+- The site-wide language switcher always lists every configured locale
+  regardless of how many pages each one has, because the build emits a
+  reachable URL for each (page → fallback to English if needed).
+
+So a 🔴 Skeleton entry in the language switcher is **not** a promise
+that the docs are translated — only that the locale build target is
+configured. The behaviour is intentional (out-of-tree contributors can
+incrementally translate a page at a time without breaking the link
+graph), but it makes the language switcher look more complete than the
+underlying content actually is.
+
+## How to read the docs site
+
+- **Always default to English** if you want the most accurate, current
+  information.
+- **Use a translated locale** only after checking this page for the
+  locale's status. If it's 🟡 or 🔴 and you hit a topic that hasn't been
+  translated, you're reading an English fallback under a translated nav
+  label.
+
+## How to help
+
+If you'd like to translate a page or fix an existing translation:
+
+1. Read the [Translation Guide](../contributing/translation-guide.md)
+   for the workflow, tooling, and style conventions.
+2. Translate one page at a time — partial translations are welcome and
+   merged incrementally.
+3. Open a PR adding the new file(s) under `docs/<locale>/<same path>`.
+   Keep filenames identical to the English source so MkDocs picks them
+   up automatically.
+4. Update this page's table to reflect the new completeness count
+   (use the recount snippet at the top of this page) and bump the
+   "Snapshot verified" date so reviewers can see when it was last
+   reconciled.
+
+Bug reports about translated pages going out of sync with the English
+source are welcome — please link the English page and the translated
+page so we can triage.
+
+## Why we ship 🔴 Skeleton locales at all
+
+Two reasons:
+
+1. **Predictable URL space.** Each locale already has its `/<locale>/`
+   subtree reachable, so when a translated page lands the link is
+   stable from day one — including links published in this guide.
+2. **Lower contributor friction.** Contributors translating a single
+   page don't have to also wire a new locale build into MkDocs config —
+   they just drop the file in.
+
+If a locale stays at 🔴 Skeleton with no contribution activity for an
+extended period, we may revisit whether to keep its build target
+enabled. That decision is tracked separately and is **not** something
+this status page silently changes.
diff --git a/docs/en/tutorial/domain-starter.md b/docs/en/tutorial/domain-starter.md
new file mode 100644
index 0000000..8b99853
--- /dev/null
+++ b/docs/en/tutorial/domain-starter.md
@@ -0,0 +1,454 @@
+# Domain-oriented FastAPI with `fastapi-domain-starter`
+
+Build a medium-sized FastAPI service with the recommended modern layout —
+**one folder per business concept** under `src/app/domains/`. This
+tutorial walks through the `fastapi-domain-starter` template end-to-end:
+how to generate it, what each top-level package does, how the bundled
+`items` example is wired, and how to add your next domain.
+
+## What you'll learn
+
+- Generating a project with `fastkit startdemo fastapi-domain-starter`
+- The role of `core`, `db`, `domains`, and `tests` in the layout
+- How a domain is split into router → service → repository → schemas → models
+- The contract for adding a new domain (copy the items folder, register the router)
+- How the bundled `/health` endpoint and `/api/v1/items` CRUD plug into the app
+
+## Prerequisites
+
+- Python 3.12+
+- FastAPI-fastkit installed (`pip install fastapi-fastkit`)
+- Comfort with basic FastAPI concepts (path operations, pydantic schemas, dependencies)
+
+If this is your first FastAPI project, start with
+[Building a Basic API Server](basic-api-server.md) instead — that
+tutorial uses the simpler `fastapi-default` template.
+
+## Step 1: Generate the project
+
+```console
+$ fastkit startdemo fastapi-domain-starter
+Enter the project name: orders-api
+Enter the author name: Developer Kim
+Enter the author email: developer@example.com
+Enter the project description: Domain-oriented orders service
+Select package manager (pip, uv, pdm, poetry) [uv]: uv
+Do you want to proceed with project creation? [y/N]: y
+```
+
+`fastkit` deploys the template, fills in placeholders, creates a virtual
+environment, and installs dependencies. After it finishes, jump in:
+
+```console
+$ cd orders-api
+$ bash scripts/run-server.sh    # or: uvicorn src.app.main:app --reload
+```
+
+API docs are then served at <http://127.0.0.1:8000/docs>.
+
+## Step 2: The generated tree
+
+```
+orders-api/
+├── README.md
+├── pyproject.toml              # PEP 621 metadata + [tool.fastapi-fastkit]
+├── requirements.txt            # pinned deps (template ships both files; you maintain them as you add packages)
+├── .env                        # SECRET_KEY, ENVIRONMENT
+├── .gitignore
+├── scripts/
+│   ├── format.sh               # black + isort
+│   ├── lint.sh                 # black --check + isort --check + mypy
+│   ├── run-server.sh           # uvicorn src.app.main:app --reload
+│   └── test.sh                 # pytest
+├── src/
+│   ├── __init__.py
+│   └── app/                    # the application package
+│       ├── __init__.py
+│       ├── main.py             # FastAPI() + middleware + api_router include
+│       ├── core/               # cross-cutting configuration
+│       │   ├── __init__.py
+│       │   └── config.py       # pydantic-settings (PROJECT_NAME, CORS, ...)
+│       ├── db/                 # persistence abstractions
+│       │   ├── __init__.py
+│       │   └── memory.py       # InMemoryStore[T] generic key-value store
+│       ├── api/                # transport-level routing
+│       │   ├── __init__.py
+│       │   ├── health.py       # GET /health
+│       │   └── router.py       # aggregates health + every domain router
+│       └── domains/            # business concepts (one folder each)
+│           ├── __init__.py
+│           └── items/          # the example domain
+│               ├── __init__.py
+│               ├── models.py       # @dataclass Item (entity)
+│               ├── schemas.py      # ItemCreate, ItemRead (pydantic)
+│               ├── repository.py   # ItemRepository over InMemoryStore
+│               ├── service.py      # ItemService + ItemNotFoundError
+│               └── router.py       # APIRouter(prefix="/items")
+└── tests/
+    ├── __init__.py
+    ├── conftest.py             # TestClient fixture, store reset
+    ├── test_health.py
+    └── test_items.py
+```
+
+The two ideas to internalize:
+
+1. **`src/app/`** is the **application package** — everything the runtime
+   imports lives here. Tests import from it (`from src.app.main import
+   app`). The outer `src/` exists so the project is `pip install`-able.
+2. **`src/app/domains/<concept>/`** is the **per-concept slice** — each
+   business concept (items, orders, users, ...) owns its own router /
+   service / repository / schemas / models and only those.
+
+## Step 3: What each top-level package does
+
+### `src/app/core/` — configuration
+
+Holds cross-cutting application configuration. The bundled `config.py`
+exposes a pydantic-settings `Settings` class read from `.env` /
+environment variables:
+
+```python
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "<project_name>"
+    ENVIRONMENT: Literal["development", "staging", "production"] = "development"
+    SECRET_KEY: str = secrets.token_urlsafe(32)
+    API_V1_PREFIX: str = "/api/v1"
+    BACKEND_CORS_ORIGINS: ... = []
+    ...
+
+settings = Settings()
+```
+
+`main.py` reads `settings.PROJECT_NAME`, `settings.API_V1_PREFIX`, and
+`settings.all_cors_origins` to wire the FastAPI app.
+
+**When to add to `core/`:** anything not specific to one domain — global
+settings, structured logging, custom middleware, security helpers, etc.
+
+### `src/app/db/` — persistence boundary
+
+Holds the abstraction over your data store. The starter ships
+`memory.py` — a process-local `InMemoryStore[T]` generic over the entity
+type. Each domain's repository wraps an `InMemoryStore`, so swapping in
+SQLAlchemy / async drivers later is a contained change: only the
+repositories need to be rewritten.
+
+```python
+class InMemoryStore(Generic[T]):
+    def list(self) -> Iterable[T]: ...
+    def get(self, id_: int) -> Optional[T]: ...
+    def add(self, item: T) -> int: ...
+    def replace(self, id_: int, item: T) -> bool: ...
+    def delete(self, id_: int) -> bool: ...
+    def clear(self) -> None: ...
+```
+
+**When to grow `db/`:** add a `session.py` with your real database
+session factory once you migrate off `InMemoryStore`. Keep the
+public method shape (`list` / `get` / `add` / ...) the same so the
+domain repositories don't have to change their internal contract.
+
+### `src/app/api/` — transport routing
+
+Two pieces:
+
+- `health.py` — a small `APIRouter` exposing `GET /health` returning
+  `{"status": "ok"}`. Side-effect-free, ideal for liveness probes.
+- `router.py` — the **top-level aggregator**. It includes the health
+  router and every domain's router, and that single combined
+  `api_router` is mounted on the FastAPI app under `/api/v1`:
+
+```python
+# src/app/api/router.py
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(items_router.router)
+```
+
+```python
+# src/app/main.py
+app.include_router(api_router, prefix=settings.API_V1_PREFIX)
+```
+
+**Why aggregate here:** when you add a new domain, you only edit
+`src/app/api/router.py` to register its router. `main.py` never changes.
+
+### `src/app/domains/<concept>/` — business slices
+
+This is where most of your code lives as the project grows. Each domain
+owns five files:
+
+| File | Role |
+|---|---|
+| `models.py` | Domain entity (a `@dataclass` in the starter; could be SQLAlchemy / SQLModel later). The internal shape — not the wire format. |
+| `schemas.py` | API I/O schemas (pydantic). Separate from the entity so the wire format can evolve without touching domain logic. |
+| `repository.py` | Data access. Wraps the store with item-typed methods. The seam where persistence is swapped in/out. |
+| `service.py` | Business logic. Routers call into `service`, never directly into `repository`. Domain-specific exceptions (e.g. `ItemNotFoundError`) live here. |
+| `router.py` | HTTP transport. Translates pydantic schemas ↔ service calls; turns domain exceptions into `HTTPException`s. |
+
+The **dependency direction** is `router → service → repository → store`.
+Each layer only depends on the layer below it. Schemas are referenced by
+the router and service; models are referenced by the repository and
+service.
+
+### `tests/`
+
+Mirrors the runtime layout — one test module per surface that has
+behavior worth pinning. The starter ships:
+
+- `conftest.py` — autouse fixture that resets the items store between
+  tests, plus a `client` fixture wrapping `TestClient(app)`.
+- `test_health.py` — verifies `GET /api/v1/health` returns 200 +
+  `{"status": "ok"}`.
+- `test_items.py` — full CRUD coverage of the items endpoints,
+  including a 404 for unknown ids and a 422 for an invalid payload.
+
+Run with:
+
+```console
+$ bash scripts/test.sh         # or: pytest
+```
+
+## Step 4: Walk through the bundled `items` domain
+
+The example domain is a CRUD over a tiny entity:
+
+```python
+# src/app/domains/items/models.py
+@dataclass
+class Item:
+    id: int
+    name: str
+    price: float
+    in_stock: bool = True
+```
+
+API schemas separate the input shape from the output shape so we can
+add server-controlled fields (`id`) and validation (price ≥ 0):
+
+```python
+# src/app/domains/items/schemas.py
+class ItemCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=120)
+    price: float = Field(ge=0)
+    in_stock: bool = True
+
+class ItemRead(BaseModel):
+    id: int
+    name: str
+    price: float
+    in_stock: bool
+    model_config = ConfigDict(from_attributes=True)
+```
+
+The repository wraps the in-memory store and assigns ids on insert:
+
+```python
+# src/app/domains/items/repository.py
+class ItemRepository:
+    def __init__(self, store: Optional[InMemoryStore[Item]] = None) -> None:
+        self._store = store if store is not None else _store
+
+    def add(self, name: str, price: float, in_stock: bool = True) -> Item:
+        item = Item(id=0, name=name, price=price, in_stock=in_stock)
+        new_id = self._store.add(item)
+        item.id = new_id
+        return item
+    # list_all / get / replace / delete / reset elided
+```
+
+The service layer is where business rules accumulate. Today it's a
+thin pass-through with one custom exception, but this is where future
+policy lives ("can't delete an item that's in an open order", etc.):
+
+```python
+# src/app/domains/items/service.py
+class ItemNotFoundError(Exception): ...
+
+class ItemService:
+    def __init__(self, repository: Optional[ItemRepository] = None) -> None:
+        self._repository = repository if repository is not None else ItemRepository()
+
+    def get_item(self, item_id: int) -> Item:
+        item = self._repository.get(item_id)
+        if item is None:
+            raise ItemNotFoundError(f"Item {item_id} does not exist")
+        return item
+    # list_items / create_item / replace_item / delete_item elided
+```
+
+The router is the only piece that knows about HTTP. Notice it takes the
+service as a FastAPI `Depends(...)` so tests can override it, and it
+maps `ItemNotFoundError` → `HTTPException(404)`:
+
+```python
+# src/app/domains/items/router.py
+router = APIRouter(prefix="/items", tags=["items"])
+
+def get_item_service() -> ItemService:
+    return ItemService()
+
+@router.get("/{item_id}", response_model=ItemRead)
+def get_item(item_id: int, service: ItemService = Depends(get_item_service)) -> ItemRead:
+    try:
+        return ItemRead.model_validate(service.get_item(item_id))
+    except ItemNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+```
+
+The full router exposes:
+
+| Method | Path | What it does |
+|---|---|---|
+| `GET` | `/api/v1/items` | List items |
+| `GET` | `/api/v1/items/{item_id}` | Read one |
+| `POST` | `/api/v1/items` | Create (returns 201) |
+| `PUT` | `/api/v1/items/{item_id}` | Replace |
+| `DELETE` | `/api/v1/items/{item_id}` | Delete (returns 204) |
+| `GET` | `/api/v1/health` | Liveness probe |
+
+Try it:
+
+```console
+$ curl -X POST http://127.0.0.1:8000/api/v1/items \
+       -H 'Content-Type: application/json' \
+       -d '{"name":"Mug","price":9.5,"in_stock":true}'
+{"id":1,"name":"Mug","price":9.5,"in_stock":true}
+
+$ curl http://127.0.0.1:8000/api/v1/items
+[{"id":1,"name":"Mug","price":9.5,"in_stock":true}]
+
+$ curl http://127.0.0.1:8000/api/v1/items/999
+{"detail":"Item 999 does not exist"}
+```
+
+## Step 5: Add your next domain
+
+The starter is designed so that **adding a domain is a copy-rename
+operation**. Say you want a `users` domain alongside `items`:
+
+### 1. Copy the `items/` folder
+
+```console
+$ cp -r src/app/domains/items src/app/domains/users
+```
+
+### 2. Rewrite the entity, schemas, and per-file class names
+
+```python
+# src/app/domains/users/models.py
+from dataclasses import dataclass
+
+@dataclass
+class User:
+    id: int
+    email: str
+    is_active: bool = True
+```
+
+```python
+# src/app/domains/users/schemas.py
+from pydantic import BaseModel, ConfigDict, Field
+
+class UserCreate(BaseModel):
+    # Plain ``str`` keeps the snippet drop-in safe. To use pydantic's
+    # built-in email validation instead, install the optional dependency
+    # (``pip install 'pydantic[email]'`` — pulls in ``email-validator``)
+    # and switch ``str`` to ``EmailStr``.
+    email: str = Field(min_length=3, max_length=320)
+    is_active: bool = True
+
+class UserRead(BaseModel):
+    id: int
+    email: str
+    is_active: bool
+    model_config = ConfigDict(from_attributes=True)
+```
+
+Rename `Item → User`, `ItemNotFoundError → UserNotFoundError`,
+`ItemRepository → UserRepository`, `ItemService → UserService` across
+`models.py`, `schemas.py`, `repository.py`, `service.py`, and
+`router.py`. Don't forget `prefix="/items"` → `prefix="/users"` and
+`tags=["items"]` → `tags=["users"]` in the router.
+
+The repository can keep the same `InMemoryStore`-backed pattern — it's
+generic over the entity type:
+
+```python
+# src/app/domains/users/repository.py
+_store: InMemoryStore[User] = InMemoryStore()
+
+class UserRepository:
+    def __init__(self, store: Optional[InMemoryStore[User]] = None) -> None:
+        self._store = store if store is not None else _store
+    # ... same shape as ItemRepository ...
+```
+
+### 3. Update the domain `__init__.py`
+
+The items domain re-exports its modules so callers can write
+`from src.app.domains.items import service`. Mirror that for users:
+
+```python
+# src/app/domains/users/__init__.py
+from src.app.domains.users import (  # noqa: F401
+    models,
+    repository,
+    router,
+    schemas,
+    service,
+)
+```
+
+### 4. Register the router in the aggregator
+
+This is the **only file outside `domains/users/` you need to touch**:
+
+```python
+# src/app/api/router.py
+from src.app.api import health
+from src.app.domains.items import router as items_router
+from src.app.domains.users import router as users_router  # ← add
+
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(items_router.router)
+api_router.include_router(users_router.router)             # ← add
+```
+
+After a server restart you'll see `/api/v1/users` mounted in `/docs`.
+
+### 5. Add tests
+
+Mirror `tests/test_items.py` as `tests/test_users.py` — same
+client-driven shape, just hit the new endpoints. The autouse store-reset
+fixture in `conftest.py` already keeps each test isolated.
+
+If you add a second domain that also uses `InMemoryStore`, broaden the
+fixture to reset its store too, or keep one fixture per domain.
+
+## Step 6: Where to go next
+
+- The [Architecture Preset Matrix](../reference/preset-feature-matrix.md)
+  shows what `fastkit init --interactive` generates for each preset,
+  including which feature selections need manual wiring under
+  `domain-starter`.
+- The [`fastapi-default` tutorial](basic-api-server.md) covers the
+  layered alternative if you'd like to compare layouts before
+  committing.
+- For database integration, the
+  [Database Integration tutorial](database-integration.md) shows the
+  PostgreSQL + SQLAlchemy + Alembic pattern. The same ideas drop into
+  `src/app/db/` and the per-domain `repository.py` files.
+
+## Recap
+
+- **Generation**: `fastkit startdemo fastapi-domain-starter` →
+  `bash scripts/run-server.sh` → docs at `/docs`.
+- **Layout**: `core/` for config, `db/` for persistence abstractions,
+  `domains/<concept>/` for business slices, `api/router.py` as the
+  single aggregation point, `tests/` mirroring runtime modules.
+- **Adding a domain**: copy `items/`, rename entity / schemas / classes,
+  update the `__init__.py` re-exports, register the router in
+  `src/app/api/router.py`, add a test module. No edits to `main.py`.
diff --git a/docs/en/user-guide/choosing-a-starter.md b/docs/en/user-guide/choosing-a-starter.md
index 003ffae..8e3839f 100644
--- a/docs/en/user-guide/choosing-a-starter.md
+++ b/docs/en/user-guide/choosing-a-starter.md
@@ -190,5 +190,9 @@ is the reference page for that.
 - [Quick Start](quick-start.md) — actually create your first project.
 - [Creating Projects](creating-projects.md) — deeper walkthrough of the
   CLI flags.
+- [Domain-oriented Project tutorial](../tutorial/domain-starter.md) —
+  if you picked `domain-starter`, this is the end-to-end walkthrough of
+  the generated tree, the bundled `items` example, and how to add your
+  next domain.
 - [Architecture Preset Matrix](../reference/preset-feature-matrix.md) —
   the full per-preset / per-feature contract.
diff --git a/docs/ko/index.md b/docs/ko/index.md
index c58d0ce..f2821ef 100644
--- a/docs/ko/index.md
+++ b/docs/ko/index.md
@@ -22,6 +22,14 @@
 
 이 프로젝트는 `SpringBoot initializer` 및 Python Django의 `django-admin` CLI 동작에서 영감을 받았습니다.
 
+!!! info "번역 상태"
+    이 문서의 **원본은 영어 (`en`)** 입니다. 한국어 번역은 일부 페이지에만
+    제공되며, 번역되지 않은 페이지는 영어 원문으로 표시됩니다. 각 언어의
+    실제 번역 진행 상황은
+    [Translation Status](reference/translation-status.md) 페이지를
+    확인해 주세요. 영어 페이지와 번역 페이지의 내용이 다르다면 영어
+    페이지를 기준으로 삼으세요.
+
 ## 주요 기능
 
 - **⚡ Immediate FastAPI project creation** : [Python Django](https://github.com/django/django)의 `django-admin` 기능에서 영감을 받은 CLI를 통해 초고속 FastAPI 워크스페이스 및 프로젝트 생성
diff --git a/mkdocs.yml b/mkdocs.yml
index aebfdc5..575c331 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -130,6 +130,7 @@ nav:
     - Your First Project: tutorial/first-project.md
     - Implementing Basic API Server: tutorial/basic-api-server.md
     - Implementing Asynchronous CRUD API: tutorial/async-crud-api.md
+    - Domain-oriented Project (Domain Starter): tutorial/domain-starter.md
     - Database Integration: tutorial/database-integration.md
     - Docker Deployment: tutorial/docker-deployment.md
     - Implementing Custom Response Handling: tutorial/custom-response-handling.md
@@ -143,6 +144,7 @@ nav:
     - FAQ: reference/faq.md
     - Architecture Preset Matrix: reference/preset-feature-matrix.md
     - Template Quality Assurance: reference/template-quality-assurance.md
+    - Translation Status: reference/translation-status.md
   - Changelog: changelog.md
 
 markdown_extensions:
diff --git a/src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl b/src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl
index 6140f08..6258739 100644
--- a/src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl
+++ b/src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl
@@ -119,6 +119,10 @@ The `FastAPI-fastkit` is an open-source project that helps Python and
 FastAPI beginners quickly set up a FastAPI-based application development
 environment in a framework-like structure.
 
+For an end-to-end walkthrough of this template — the generated tree,
+the bundled `items` example, and how to add your next domain — see the
+[**Domain-oriented Project tutorial**](https://bnbong.github.io/FastAPI-fastkit/tutorial/domain-starter/).
+
 ### Template Information
 - Template creator: [bnbong](mailto:bbbong9@gmail.com)
 - FastAPI-fastkit project maintainer: [bnbong](mailto:bbbong9@gmail.com)