{"id":240,"date":"2026-06-19T19:10:07","date_gmt":"2026-06-19T11:10:07","guid":{"rendered":"https:\/\/erishen.cn\/?page_id=240"},"modified":"2026-06-19T19:28:55","modified_gmt":"2026-06-19T11:28:55","slug":"monorepo-nextjs-fastapi-knowledge-base","status":"publish","type":"page","link":"https:\/\/erishen.cn\/?page_id=240","title":{"rendered":"Building a Full-Stack Knowledge Base Platform: Monorepo + Next.js 14 + FastAPI in Practice"},"content":{"rendered":"

<\/p>\n

A full-stack development practice based on Turborepo + Next.js 14 + FastAPI, suitable as an architecture reference for small to medium-sized projects.<\/p>\n

<\/p>\n

Project Background<\/h2>\n

<\/p>\n

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 \u2014 not just for personal knowledge management, but also as an open-source reference for other developers.<\/p>\n

<\/p>\n

Core requirements<\/strong>: unified note management, online editing with real-time preview, elegant documentation display, and exploration of full-stack best practices.<\/p>\n

<\/p>\n

Technology Selection & Architecture<\/h2>\n

<\/p>\n

Why Monorepo?<\/h3>\n

<\/p>\n\n\n\n\n\n\n\n\n\n
Dimension<\/td>\nMulti-repo<\/td>\nMonorepo (Turborepo)<\/td>\n<\/tr>\n<\/thead>\n
Code sharing<\/td>\nPublish npm packages<\/td>\nWorkspace direct reference<\/td>\n<\/tr>\n
Version control<\/td>\nIndependent versions<\/td>\nUnified versioning<\/td>\n<\/tr>\n
CI\/CD<\/td>\nMultiple pipelines<\/td>\nSingle build process<\/td>\n<\/tr>\n
Dependency mgmt<\/td>\nVersion conflicts likely<\/td>\nUnified dependency management<\/td>\n<\/tr>\n
Cross-package testing<\/td>\nDifficult<\/td>\nStraightforward<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

<\/p>\n

Core Tech Stack<\/h3>\n

<\/p>\n

– Frontend<\/strong>: Next.js 14 (App Router), React 18, TypeScript 5, Turborepo<\/p>\n

– Backend<\/strong>: FastAPI, Python 3.10+, Pydantic v2, SQLAlchemy, Alembic, Uvicorn<\/p>\n

– Data<\/strong>: MySQL 8.0, Redis, Supabase (auth)<\/p>\n

– Content<\/strong>: next-mdx-remote, @tailwindcss\/typography<\/p>\n

– Styling<\/strong>: Tailwind CSS, styled-components<\/p>\n

– Dev tools<\/strong>: ESLint + Prettier, Storybook, Changeset<\/p>\n

– Deploy<\/strong>: Vercel (frontend), Docker + Nginx (backend), pnpm<\/p>\n

<\/p>\n

Architecture Overview<\/h3>\n

<\/p>\n

\nUser Access Layer\n  web.erishen.cn (Frontend)  |  admin.erishen.cn (Admin)\n              \u2193\nAPI Gateway: api.erishen.cn (FastAPI)\n  - Items API  |  Auth API  |  Docs API  |  Redis API\n              \u2193\n    MySQL 8.0          Redis\n<\/code><\/pre>\n
<\/p>\n
Monorepo Structure<\/h3>\n
<\/p>\n
\napps\/\n\u251c\u2500\u2500 web\/          # Main app (port 3000) - doc browsing\n\u2514\u2500\u2500 admin\/        # Admin panel (port 3003) - doc editing\n\npackages\/\n\u251c\u2500\u2500 ui\/           # Shared UI component library\n\u251c\u2500\u2500 api-client\/   # API client\n\u251c\u2500\u2500 utils\/        # Utility functions\n\u251c\u2500\u2500 types\/        # Type definitions\n\u2514\u2500\u2500 config\/       # Shared configuration\n\ndocs\/             # Knowledge base Markdown source files\nscripts\/          # Utility scripts\n<\/code><\/pre>\n
<\/p>\n
Backend Layered Architecture<\/h3>\n
<\/p>\n
\nfastapi-web\/\n\u251c\u2500\u2500 app\/\n\u2502   \u251c\u2500\u2500 routers\/       # API routing layer\n\u2502   \u251c\u2500\u2500 crud.py        # Database operations\n\u2502   \u251c\u2500\u2500 models.py      # SQLAlchemy models\n\u2502   \u251c\u2500\u2500 schemas.py     # Pydantic validation\n\u2502   \u251c\u2500\u2500 security.py    # JWT, auth\n\u2502   \u251c\u2500\u2500 middleware.py   # Logging, rate limiting\n\u2502   \u251c\u2500\u2500 factory.py     # App factory pattern\n\u2502   \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 alembic\/           # Database migrations\n\u251c\u2500\u2500 tests\/\n\u251c\u2500\u2500 Dockerfile\n\u2514\u2500\u2500 docker-compose.yml\n<\/code><\/pre>\n
<\/p>\n
Core Features<\/h2>\n
<\/p>\n
Frontend Knowledge Base<\/h3>\n
<\/p>\n
– Structured document browsing with MDX rendering<\/p>\n
– Document loading from Admin API with local filesystem fallback<\/p>\n
– Search, code highlighting, responsive design<\/p>\n
<\/p>\n
Admin Application<\/h3>\n
<\/p>\n
– Online Markdown editor for docs\/<\/p>\n
– Dual authentication demo (NextAuth.js + Passport.js)<\/p>\n
– CSRF protection, Redis cache demos<\/p>\n
– FastAPI service proxy<\/p>\n
<\/p>\n
FastAPI Backend<\/h3>\n
<\/p>\n
Full CRUD REST API with JWT auth, rate limiting, suspicious access detection, CORS, SQL injection prevention (ORM), XSS protection.<\/p>\n
<\/p>\n
Shared Component Library<\/h3>\n
<\/p>\n
\n\/\/ Import in any app with full TypeScript support\nimport { Button, Card, Input } from \"@interview\/ui\";\n<Button variant=\"primary\" size=\"large\">Click Me<\/Button>\n<\/code><\/pre>\n
<\/p>\n
Deployment<\/h2>\n
<\/p>\n
Frontend: Vercel<\/h3>\n
– Auto-deploy on git push<\/p>\n
– Serverless functions<\/p>\n
– Global CDN, automatic HTTPS<\/p>\n
<\/p>\n
Backend: Docker + Nginx<\/h3>\n
<\/p>\n
\n# docker-compose.prod.yml\nservices:\n  app:\n    build: .\n    container_name: fastapi-web-app\n    network_mode: host\n    restart: always\n    environment:\n      - APP_ENV=production\n      - PORT=8086\n    healthcheck:\n      test: [\"CMD\", \"curl\", \"-f\", \"http:\/\/localhost:8086\/health\"]\n      interval: 30s\n      retries: 3\n<\/code><\/pre>\n
<\/p>\n
Key Takeaways<\/h2>\n
<\/p>\n
– Monorepo suits small-medium teams<\/strong>: Code sharing and unified dependencies, but evaluate carefully for massive projects<\/p>\n
– Pragmatic tech choices<\/strong>: Next.js 14 + FastAPI is efficient for medium projects<\/p>\n
– Engineering matters<\/strong>: Turborepo, Docker, CI\/CD significantly improve dev efficiency and deployment reliability<\/p>\n
– Iterate from simple<\/strong>: Implement core features first, then progressively enhance<\/p>\n
– Security throughout<\/strong>: Even small projects need basic security (JWT, rate limiting, CORS)<\/p>\n
<\/p>\n
Links<\/h2>\n
<\/p>\n
– Frontend: github.com\/erishen\/interview<\/a><\/p>\n
– Backend: github.com\/erishen\/fastapi-web<\/a><\/p>\n
– Web App: web.erishen.cn<\/a><\/p>\n
– Admin: admin.erishen.cn<\/a><\/p>\n
– API: api.erishen.cn<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
A full-stack development practice based on Turborepo +  […]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"english_url":"","chinese_url":"https:\/\/erishen.cn\/?p=180","footnotes":""},"class_list":["post-240","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/erishen.cn\/index.php?rest_route=\/wp\/v2\/pages\/240","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/erishen.cn\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/erishen.cn\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/erishen.cn\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/erishen.cn\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=240"}],"version-history":[{"count":3,"href":"https:\/\/erishen.cn\/index.php?rest_route=\/wp\/v2\/pages\/240\/revisions"}],"predecessor-version":[{"id":256,"href":"https:\/\/erishen.cn\/index.php?rest_route=\/wp\/v2\/pages\/240\/revisions\/256"}],"wp:attachment":[{"href":"https:\/\/erishen.cn\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=240"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}