Phase 1 Architecture Approach

Backend + Frontend structure for auth, user management, project CRUD, activity logging

A

Monorepo — Single Repo, Separate Packages

Structure:

theroad-i1/
├── backend/          # FastAPI app
│   ├── app/
│   │   ├── api/      # Route handlers (auth, users, projects)
│   │   ├── core/     # Config, security, DB engine
│   │   ├── models/   # SQLAlchemy models
│   │   ├── schemas/  # Pydantic schemas (OpenAPI)
│   │   ├── services/ # Business logic
│   │   ├── modules/  # LLM analysis (future)
│   │   └── logging/  # Activity log module
│   └── i18n/         # Localized strings (JSON)
├── frontend/         # React + Vite + TS
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── api/      # API client
│   │   └── i18n/     # UI strings (JSON)
│   └── vite.config.ts
├── prompts/          # External prompt files (versioned)
├── docs/             # Dev log, specs
└── projects/         # Project SQLite DBs + assets

Pros

  • Clean separation of backend/frontend
  • Backend and frontend can be developed/deployed independently
  • Standard pattern, easy to understand
  • Each module has clear boundaries

Cons

  • Need CORS config during dev
  • Two dev servers to run

★ Recommended

B

Integrated — FastAPI serves React build

Structure:

theroad-i1/
├── app/              # FastAPI app (serves API + static)
│   ├── api/
│   ├── core/
│   ├── models/
│   └── ...
├── web/              # React source
│   └── src/
├── static/           # Built React output (served by FastAPI)
└── ...

Pros

  • Single server, no CORS issues
  • Simpler deployment

Cons

  • Build step needed before serving
  • Tighter coupling
  • Hot reload harder during dev
C

Hybrid — Vite proxy to FastAPI

Structure: Same as A, but Vite dev server proxies API calls to FastAPI. Production: FastAPI serves built static files.

Pros

  • Best dev experience (hot reload + no CORS)
  • Clean separation in code
  • Single URL during dev

Cons

  • Vite proxy config needed
  • Slightly more setup