Blueprint4FastAPI is a full-stack template with:

• Backend: FastAPI + SQLAlchemy + Alembic + Redis
• Frontend: React + TypeScript + OpenAPI-generated API types
• Monolithic static serving support (frontend build copied into backend static path)

1. Agent/workflow rules: AGENTS.md
2. Deployment guide: DEPLOY.md
3. Backend engineering rules: src/backend/BACKEND.md
4. Frontend engineering rules: src/frontend/FRONTEND.md
5. Backend quick guide: src/backend/README.md
6. Frontend quick guide: src/frontend/README.md

Localized documentation rule:

• Keep translated/localized docs under notes/<locale>/....
• Mirror the original document structure by domain (backend, frontend, etc.).

Current locale example (ko):

1. Root guide: notes/ko/README.md
2. Agent/workflow rules: notes/ko/AGENTS.md
3. Deployment guide: notes/ko/DEPLOY.md
4. Backend engineering rules: notes/ko/backend/BACKEND.md
5. Frontend engineering rules: notes/ko/frontend/FRONTEND.md
6. Backend test guide: notes/ko/backend/TEST.md
7. Frontend test guide: notes/ko/frontend/TEST.md

src/
 backend/
 frontend/
docker/
 scripts/

1. Initialize env files:

make init

2. Run backend (local development):

make backend-install
make backend-dev

3. Run frontend (local development):

make frontend-install
make frontend-dev

4. Open:

• Backend API docs: http://localhost:8000/docs
• Frontend app (Vite): http://localhost:5173

Run make help to list the available workflow hooks.

Common targets:

make install # Install backend and frontend dependencies
make backend-dev # Run FastAPI development server
make frontend-dev # Run Vite development server
make build # Build backend environment and frontend artifacts
make test # Run backend and frontend tests
make check # Run backend lint and frontend format checks
make format # Format backend and frontend code
make ci # Run check, test, and build

Docker targets:

make docker-build
make docker-up
make docker-logs DOCKER_SERVICE=app
make docker-down
make docker-deploy
make docker-export
make docker-observability-up
make docker-observability-down

1. Prepare env:

make init

2. Build app image:

make docker-build

3. Start services (app + optional local postgres/redis based on docker/.env):

make docker-up

4. View logs:

make docker-logs DOCKER_SERVICE=app

5. Stop services:

make docker-down

6. One-shot deploy (build + recreate + export tar):

make docker-deploy

7. Export app image tar:

make docker-export

Exported image files are stored in docker/artifacts/.

Backend:

make backend-format
make backend-test

Frontend:

make frontend-format
make frontend-build