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

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

Related posts

• RAG chat app
• Production React SSR framework
• AI tool server Lobster

Source code navigation

The full project spans two repos: erishen/interview (Next.js monorepo) and erishen/fastapi-web (FastAPI backend).

Frontend monorepo (interview)

File	What it does
turbo.json	Turborepo task pipeline: build / dev / lint
package.json	Root workspace aggregating apps/* and packages/*
apps/web/package.json	Web app dependencies and scripts
packages/ui/package.json	Shared UI package config
packages/ui/src/components/Button.tsx	Shared Button component
packages/ui/src/components/Card.tsx	Shared Card component
apps/web/src/lib/docs.ts	Docs data layer (reads KB content under RSC)

Backend (fastapi-web)

File	What it does
app/factory.py	create_app() factory wiring routers / middleware / CORS
app/main.py	Entry point, launches uvicorn
app/routers/items.py	items router (CRUD + auth dependency)
app/schemas.py	Pydantic request / response models
app/security.py	Auth and rate-limiting logic
app/middleware.py	Custom middleware (logging / timing)
docker-compose.prod.yml	Prod orchestration (web + db + redis)