https://github.com/nokodo-labs/monorepo-template
Modern full-stack boilerplate: FastAPI + Svelte 5. Production-ready with multi-stage builds.
https://github.com/nokodo-labs/monorepo-template
docker fastapi fullstack github-actions monorepo nginx postgresql production-ready pydantic python ruff sqlalchemy svelte sveltekit tailwindcss template typescript vite
Last synced: 5 months ago
JSON representation
Modern full-stack boilerplate: FastAPI + Svelte 5. Production-ready with multi-stage builds.
- Host: GitHub
- URL: https://github.com/nokodo-labs/monorepo-template
- Owner: nokodo-labs
- License: bsd-3-clause
- Created: 2025-10-28T08:00:21.000Z (9 months ago)
- Default Branch: dev
- Last Pushed: 2026-01-27T08:54:09.000Z (6 months ago)
- Last Synced: 2026-01-27T20:59:41.581Z (6 months ago)
- Topics: docker, fastapi, fullstack, github-actions, monorepo, nginx, postgresql, production-ready, pydantic, python, ruff, sqlalchemy, svelte, sveltekit, tailwindcss, template, typescript, vite
- Language: Svelte
- Homepage: https://nokodo-labs.github.io/monorepo-template/
- Size: 730 KB
- Stars: 19
- Watchers: 0
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
---
Monorepo Template
**Modern & production-ready full-stack template that saves you weeks of setup: FastAPI backend + Svelte 5 frontend with containerization, full CI/CD, VS Code support, and AI integrations.**
[](LICENSE)
[](https://github.com/nokodo-labs/monorepo-template/stargazers)
[](https://github.com/nokodo-labs/monorepo-template/issues)
[](https://github.com/nokodo-labs/monorepo-template/pulls)
[](https://www.python.org/downloads/)
[](https://nodejs.org/)
## 🛠️ Stack
- **Backend**: FastAPI (Python 3.13+), SQLAlchemy 2.0+, Pydantic, PostgreSQL 17, Alembic, uv
- **Frontend**: Svelte 5, Vite 6, Tailwind 4, TypeScript, native fetch (zero HTTP deps)
- **Type Safety**: OpenAPI TypeScript generator (auto-sync backend → frontend types)
- **Dev**: VS Code (tasks, debugger, extensions), Ruff, pytest, AI instructions
- **Deploy**: Docker Compose with production configs
## ✨ Features
- ⚡ **Opinionated by design**: Deliberate choices, cohesive stack, no decision fatigue
- 🏗️ **Production infrastructure**: PostgreSQL 17, multi-stage Docker builds, Nginx configs
- 🔒 **End-to-end type safety**: Python type hints → OpenAPI → auto-generated TypeScript types
- 🤖 **Full CI/CD pipeline**: Automated testing, Docker builds, GHCR publishing, releases
- 🧪 **Complete test setup**: pytest (backend) + Vitest (frontend) with fixtures and full coverage
- 📐 **Modern code standards**: EditorConfig, Ruff, ESLint, Prettier pre-configured
- 💾 **Persistent data storage**: Volume-mounted data directory
- 🛠️ **VS Code integration**: Tasks, debugger configs, recommended extensions
- 🤖 **AI agents ready**: Premade instructions & prompts with extensible patterns
- 🎯 **Minimal boilerplate**: No business logic, just a working foundation
- 🔮 **Future-proof stack**: Latest stable versions of everything, zero tech debt from day one
## 🚀 Quick Start
### 1️⃣ Create Your Repository
- Click **"Use this template"** on GitHub → Create your repo
- Clone your new repository locally
### 2️⃣ Customize Project
Rename `backend/project_slug/` to your project name and update references. See [docs/setup.md](docs/setup.md#initial-customization-required) for detailed instructions.
### 3️⃣ Start Development
```bash
cd .docker
docker compose up -d
```
**Your services:**
- Frontend: http://localhost
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/v1/docs
> 💡 **VS Code users**: Open the workspace to get tasks, debugger configs, and recommended extensions automatically.
### 4️⃣ Deploy to Production
CI/CD automatically builds and pushes Docker images to **GitHub Container Registry (GHCR)** on every commit. Images are tagged as:
- `ghcr.io/your-org/your-repo:latest` → production branch
- `ghcr.io/your-org/your-repo:dev` → dev branch
- `ghcr.io/your-org/your-repo:v1.2.3` → releases
**Deploy with Docker:**
```bash
# Pull pre-built images and deploy
docker compose pull
docker compose up -d
```
> 💡 **Tip**: See [docs/setup.md](docs/setup.md#production-deployment) for full deployment instructions and environment configuration.
## 📁 Structure
```
backend/
├── api/ # FastAPI application
│ ├── api/v1/endpoints/ # Route handlers
│ ├── core/ # Config, database
│ ├── models/ # SQLAlchemy ORM
│ ├── schemas/ # Pydantic validation
│ ├── tests/ # API & ORM tests
│ └── alembic/ # Database migrations
├── project_slug/ # SDK/service layer (rename me!)
│ └── tests/ # SDK unit tests (optional)
├── tests/ # E2E integration tests
└── data/ # Data storage (volume mounted)
frontend/
├── src/
│ ├── lib/ # Components
│ └── main.ts # Entry point
└── nginx.conf # Production server
.docker/ # Docker configs
├── Dockerfile.backend # Backend build
├── Dockerfile.frontend # Frontend build
├── docker-compose.yml # Production
└── docker-compose.dev.yml # Development
.github/ # CI/CD, Dependabot, CODEOWNERS
.vscode/ # Editor config, tasks, debugger
tools/release_please/ # Release automation config
```
### 🏗️ Architecture
**Backend:**
- **`api/`**: FastAPI app, routes, ORM, database setup
- **`project_slug/`**: Business logic SDK that can be packaged separately for pip/uv/PyPI distribution
- **Testing**: 3 tiers (API tests in `api/tests/`, SDK tests in `project_slug/tests/`, E2E in `tests/`)
- **URLs**: `/v1/users` (no `/api` prefix - deploy on `api.yourdomain.com`)
**Frontend:**
- **Native fetch** - Zero HTTP library dependencies, uses web standards
- **OpenAPI types** - Auto-generated TypeScript types from FastAPI schema
- **Type safety** - Backend changes = compile errors in frontend if incompatible
## 📄 License
BSD 3-Clause - See [LICENSE](LICENSE) for details.