Building a Full-Stack Knowledge Base Platform: Monorepo + Next.js 14 + FastAPI in Practice

🇨🇳 中文版

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)