Merge pull request #57 from bnbong/dev

[DOCS] update docs

Author: bnbong

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

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)

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)
@@ -275,35 +281,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 +337,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 +453,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>
@@ -467,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