Architecture & System Design
Architecture & System Design
6 min readMonorepo & Tech Stack Architecture
Full breakdown of npm workspaces monorepo: Next.js frontend, FastAPI backend, MySQL 8.0, and shared UI primitives.
Monorepo & Tech Stack Architecture
LeadForge AI is structured as an enterprise-grade npm workspaces monorepo designed for high throughput, data integrity, and strict separation of concerns.
1. Repository Layout
text
leadforge-ai/
├── apps/
│ ├── api/ # FastAPI Python 3.11+ Backend
│ │ ├── app/
│ │ │ ├── ai/ # OpenAI & heuristic pitch engines
│ │ │ ├── api/v1/routes/ # FastAPI REST endpoints
│ │ │ ├── core/ # Security, Auth, TOTP 2FA, DB session
│ │ │ ├── discovery/ # Google Places, GMB Profiles, Contact Crawler
│ │ │ ├── models/ # SQLAlchemy 2.0 mapped models
│ │ │ └── services/ # Core business logic & provider wrappers
│ │ └── alembic/ # Database schema migrations
│ │
│ └── web/ # Next.js 15 App Router Frontend
│ ├── src/
│ │ ├── app/ # App router pages (dashboard, auth, admin)
│ │ ├── components/ # High-end React 19 UI components
│ │ └── lib/ # Centralized API client wrappers
│
├── packages/
│ ├── config/ # Shared ESLint, Prettier, TypeScript config
│ ├── types/ # Shared type contracts
│ └── ui/ # Shared @leadforge/ui design system2. Core Runtime Stack
| Layer | Technology | Details |
|---|---|---|
| Frontend | Next.js 15 (App Router) | React 19, TypeScript, Tailwind CSS, Lucide icons, Framer Motion |
| Backend | Python 3.11+ / FastAPI | Uvicorn ASGI, Pydantic v2, SlowAPI rate limiting |
| Database | MySQL 8.0+ | SQLAlchemy 2.0 ORM, PyMySQL, Alembic migrations |
| Auth System | Native JWT + TOTP 2FA | AES-256 encrypted TOTP keys, bcrypt password hashing |
| Queue Worker | MySQL Queue Jobs | Dedicated background worker polling queue_jobs |
Was this article helpful?
Help us improve LeadForge documentation with your feedback.