A full-stack development practice based on Turborepo + Next.js 14 + FastAPI, suitable as an architecture reference for small to medium-sized projects.
Project Background
After years of development, I found my technical knowledge scattered across projects and notes. To systematically organize this knowledge, I built a technical knowledge base platform — not just for personal knowledge management, but also as an open-source reference for other developers.
Core requirements: unified note management, online editing with real-time preview, elegant documentation display, and exploration of full-stack best practices.
Technology Selection & Architecture
Why Monorepo?
| Dimension | Multi-repo | Monorepo (Turborepo) |
| Code sharing | Publish npm packages | Workspace direct reference |
| Version control | Independent versions | Unified versioning |
| CI/CD | Multiple pipelines | Single build process |
| Dependency mgmt | Version conflicts likely | Unified dependency management |
| Cross-package testing | Difficult | Straightforward |
Core Tech Stack
– Frontend: Next.js 14 (App Router), React 18, TypeScript 5, Turborepo
– Backend: FastAPI, Python 3.10+, Pydantic v2, SQLAlchemy, Alembic, Uvicorn
– Data: MySQL 8.0, Redis, Supabase (auth)
– Content: next-mdx-remote, @tailwindcss/typography
– Styling: Tailwind CSS, styled-components
– Dev tools: ESLint + Prettier, Storybook, Changeset
– Deploy: Vercel (frontend), Docker + Nginx (backend), pnpm
Architecture Overview
User Access Layer
web.erishen.cn (Frontend) | admin.erishen.cn (Admin)
↓
API Gateway: api.erishen.cn (FastAPI)
- Items API | Auth API | Docs API | Redis API
↓
MySQL 8.0 Redis
Monorepo Structure
apps/
├── web/ # Main app (port 3000) - doc browsing
└── admin/ # Admin panel (port 3003) - doc editing
packages/
├── ui/ # Shared UI component library
├── api-client/ # API client
├── utils/ # Utility functions
├── types/ # Type definitions
└── config/ # Shared configuration
docs/ # Knowledge base Markdown source files
scripts/ # Utility scripts
Backend Layered Architecture
fastapi-web/
├── app/
│ ├── routers/ # API routing layer
│ ├── crud.py # Database operations
│ ├── models.py # SQLAlchemy models
│ ├── schemas.py # Pydantic validation
│ ├── security.py # JWT, auth
│ ├── middleware.py # Logging, rate limiting
│ ├── factory.py # App factory pattern
│ └── ...
├── alembic/ # Database migrations
├── tests/
├── Dockerfile
└── docker-compose.yml
Core Features
Frontend Knowledge Base
– Structured document browsing with MDX rendering
– Document loading from Admin API with local filesystem fallback
– Search, code highlighting, responsive design
Admin Application
– Online Markdown editor for docs/
– Dual authentication demo (NextAuth.js + Passport.js)
– CSRF protection, Redis cache demos
– FastAPI service proxy
FastAPI Backend
Full CRUD REST API with JWT auth, rate limiting, suspicious access detection, CORS, SQL injection prevention (ORM), XSS protection.
Shared Component Library
// Import in any app with full TypeScript support
import { Button, Card, Input } from "@interview/ui";
<Button variant="primary" size="large">Click Me</Button>
Deployment
Frontend: Vercel
– Auto-deploy on git push
– Serverless functions
– Global CDN, automatic HTTPS
Backend: Docker + Nginx
# docker-compose.prod.yml
services:
app:
build: .
container_name: fastapi-web-app
network_mode: host
restart: always
environment:
- APP_ENV=production
- PORT=8086
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8086/health"]
interval: 30s
retries: 3
Key Takeaways
– Monorepo suits small-medium teams: Code sharing and unified dependencies, but evaluate carefully for massive projects
– Pragmatic tech choices: Next.js 14 + FastAPI is efficient for medium projects
– Engineering matters: Turborepo, Docker, CI/CD significantly improve dev efficiency and deployment reliability
– Iterate from simple: Implement core features first, then progressively enhance
– Security throughout: Even small projects need basic security (JWT, rate limiting, CORS)
Links
– Frontend: github.com/erishen/interview
– Backend: github.com/erishen/fastapi-web
– Web App: web.erishen.cn
– Admin: admin.erishen.cn
– API: api.erishen.cn