# tej-carpenter/sidekick architecture

> Architecture diagram of the GitHub repository tej-carpenter/sidekick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tej-carpenter/sidekick
- Repository: https://github.com/tej-carpenter/sidekick

## Overview

1. **High-level shape**
   This is a three-tier monorepo: a **Next.js frontend** in `frontend/`, a **FastAPI backend** in `backend/`, and a small **Node BFF/service** in `bff/`. The main product flow is frontend → backend API → database/AI/vector services.

2. **Frontend boundary**
   The frontend uses **Next.js App Router** with route groups for **auth** and **dashboard**. Pages are split by feature: login/signup, dashboard, events, insights, knowledge library, roadmaps, profile, and sidekick chat. Shared UI lives under `src/components/`, while `src/lib/api.ts` is the main client-side API boundary to the backend.

3. **Backend API boundary**
   The backend is organized as a domain API with route modules under `backend/app/api/routes/`: `auth`, `users`, `documents`, `events`, `insights`, `roadmaps`, `sidekick`, and `diagnostics`. This suggests the backend is the authoritative application layer for identity, knowledge retrieval, roadmap generation, event tracking, and AI chat.

4. **Core backend layers**
   The backend follows a standard FastAPI layering model:
   - `core/` for config and JWT/security logic
   - `db/` for SQLAlchemy models and DB connection
   - `schemas/` for Pydantic request/response models
   - `services/` for business logic and AI/vector integrations  
   `api/deps.py` likely wires shared dependencies such as DB sessions and authenticated users.

5. **Persistent data store**
   Primary structured persistence is **PostgreSQL** via **SQLAlchemy 2.0 async** and **Alembic** migrations. The repo includes migration scripts, Supabase SQL helpers, and trigger SQL, indicating the backend is designed to run against a hosted Postgres deployment and keep database schema/state in sync across environments.

6. **Document intelligence pipeline**
   Uploaded files are stored locally under `backend/uploads/`. The document processing path is centered in `services/document_processor.py`, which likely extracts text, chunks documents, classifies them, and prepares them for retrieval. This is the ingestion boundary for PDFs/DOCX files and the source of grounded answers.

7. **Vector/RAG subsystem**
   Semantic retrieval is handled by `services/vector_store.py` with **ChromaDB** persistence under `backend/chroma_data/`. This is the repo’s main RAG boundary: documents are embedded and indexed there, then queried during sidekick Q&A so responses can cite source documents/pages.

8. **AI orchestration**
   `services/gemini_service.py` is the model integration layer for **Google Gemini**, and `services/insight_engine.py` appears to turn profile + document signals into proactive insights. This means AI is not only used for chat, but also for classification, roadmap generation, insight detection, and extracting events/deadlines.

9. **Product feature flows**
   The main functional flows are:
   - **Sidekick chat**: user asks questions → backend retrieves relevant context from Chroma/Postgres → Gemini generates an answer
   - **Roadmaps**: user request → AI generates a persistent multi-step plan stored in the database
   - **Insights**: backend analyzes uploaded documents and profile data to produce actionable alerts
   - **Events**: deadlines/exams are extracted from documents or chats and written into the planner feature

10. **Authentication and user state**
    Auth is **JWT-based**. The `auth` route plus `core/security.py` and `users` route define the security boundary, while the frontend has dedicated auth pages and providers. The profile/dashboard state is persistent and used to personalize responses, so user identity and student context are core inputs to nearly every AI feature.

11. **Operational tooling**
    The repo includes Alembic migrations, database validation/test scripts, and a `diagnostics` API route, which suggests the system is actively debugged around DB connectivity, schema state, and AI/roadmap generation failures. There is also a `bff/` Node entrypoint, but the main application architecture is clearly centered on the FastAPI backend and Next.js client.

Main entry points: [`backend/app/api/routes`](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/api/routes) (API routes), [`backend/app/services`](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/services) (Services), [`frontend/src/app`](https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app) (Next.js app), [`backend/app/main.py`](https://github.com/tej-carpenter/sidekick/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js app<br/>web client"]
  node_frontend_auth["Auth pages<br/>route group"]
  node_frontend_dashboard["Dashboard pages<br/>route group"]
  node_frontend_components["Shared UI<br/>ui components"]
  node_frontend_api["API client<br/>client boundary<br/>[api.ts]"]
end

subgraph group_backend["Backend API"]
  node_backend_main["FastAPI app<br/>api server<br/>[main.py]"]
  node_backend_routes["API routes<br/>domain routes"]
  node_backend_auth["Auth/users<br/>identity<br/>[auth.py]"]
  node_backend_docs["Documents<br/>ingestion API<br/>[documents.py]"]
  node_backend_intelligence["AI features<br/>feature APIs<br/>[sidekick.py]"]
  node_backend_core["Core config<br/>security/config"]
  node_backend_db[("DB layer<br/>orm persistence")]
  node_backend_schemas["Schemas<br/>pydantic models"]
  node_backend_services["Services<br/>business logic"]
end

subgraph group_bff["BFF"]
  node_bff_server["Node BFF<br/>[server.ts]"]
end

subgraph group_storage["Data/State"]
  node_vector_store[("Vector store<br/>rag index")]
  node_postgres[("Postgres<br/>primary database")]
  node_uploads["Uploads<br/>file store"]
end

node_frontend_app -->|"routes"| node_frontend_auth
node_frontend_app -->|"routes"| node_frontend_dashboard
node_frontend_app -->|"uses"| node_frontend_components
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -->|"HTTP"| node_backend_main
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"includes"| node_backend_auth
node_backend_routes -->|"includes"| node_backend_docs
node_backend_routes -->|"includes"| node_backend_intelligence
node_backend_routes -->|"depends on"| node_backend_core
node_backend_routes -->|"validates"| node_backend_schemas
node_backend_routes -->|"orchestrates"| node_backend_services
node_backend_services -->|"reads/writes"| node_backend_db
node_backend_services -->|"retrieves"| node_vector_store
node_backend_services -->|"ingests"| node_uploads
node_backend_db -->|"persists"| node_postgres
node_backend_services -->|"migrates"| node_postgres
node_backend_services -->|"uses"| node_backend_core
node_backend_intelligence -->|"invokes"| node_backend_services
node_bff_server -.->|"proxies"| node_backend_main

click node_frontend_app "https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app"
click node_frontend_auth "https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app/(auth)"
click node_frontend_dashboard "https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app/(dashboard)"
click node_frontend_components "https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/components"
click node_frontend_api "https://github.com/tej-carpenter/sidekick/blob/main/frontend/src/lib/api.ts"
click node_backend_main "https://github.com/tej-carpenter/sidekick/blob/main/backend/app/main.py"
click node_backend_routes "https://github.com/tej-carpenter/sidekick/tree/main/backend/app/api/routes"
click node_backend_auth "https://github.com/tej-carpenter/sidekick/blob/main/backend/app/api/routes/auth.py"
click node_backend_docs "https://github.com/tej-carpenter/sidekick/blob/main/backend/app/api/routes/documents.py"
click node_backend_intelligence "https://github.com/tej-carpenter/sidekick/blob/main/backend/app/api/routes/sidekick.py"
click node_backend_core "https://github.com/tej-carpenter/sidekick/tree/main/backend/app/core"
click node_backend_db "https://github.com/tej-carpenter/sidekick/tree/main/backend/app/db"
click node_backend_schemas "https://github.com/tej-carpenter/sidekick/tree/main/backend/app/schemas"
click node_backend_services "https://github.com/tej-carpenter/sidekick/tree/main/backend/app/services"
click node_vector_store "https://github.com/tej-carpenter/sidekick/tree/main/backend/chroma_data"
click node_postgres "https://github.com/tej-carpenter/sidekick/tree/main/backend/alembic"
click node_uploads "https://github.com/tej-carpenter/sidekick/tree/main/backend/uploads"
click node_bff_server "https://github.com/tej-carpenter/sidekick/blob/main/bff/src/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_auth,node_frontend_dashboard,node_frontend_components,node_frontend_api toneBlue
class node_backend_main,node_backend_routes,node_backend_auth,node_backend_docs,node_backend_intelligence,node_backend_core,node_backend_db,node_backend_schemas,node_backend_services toneAmber
class node_bff_server toneMint
class node_vector_store,node_postgres,node_uploads toneRose
```

## Components

### Frontend

Next.js client app with auth and dashboard routes.

- [Next.js app](https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app): web client · App Router frontend for auth, dashboard, and feature pages. · `frontend/src/app`
- [Auth pages](https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app/(auth)): route group · Login and signup entry points. · `frontend/src/app/(auth)`
- [Dashboard pages](https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/app/(dashboard)): route group · Main authenticated product surfaces. · `frontend/src/app/(dashboard)`
- [Shared UI](https://github.com/tej-carpenter/sidekick/tree/main/frontend/src/components): ui components · Reusable widgets, providers, and markdown/rendering helpers. · `frontend/src/components`
- [API client](https://github.com/tej-carpenter/sidekick/blob/main/frontend/src/lib/api.ts): client boundary · Frontend backend-access layer. · `frontend/src/lib/api.ts`

### Backend API

FastAPI application with domain routes, services, and persistence.

- [FastAPI app](https://github.com/tej-carpenter/sidekick/blob/main/backend/app/main.py): api server · Application entrypoint wiring routes and dependencies. · `backend/app/main.py`
- [API routes](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/api/routes): domain routes · HTTP surface for auth, users, documents, events, insights, roadmaps, sidekick, and diagnostics. · `backend/app/api/routes`
- [Auth/users](https://github.com/tej-carpenter/sidekick/blob/main/backend/app/api/routes/auth.py): identity · JWT auth and user profile endpoints. · `backend/app/api/routes/auth.py`
- [Documents](https://github.com/tej-carpenter/sidekick/blob/main/backend/app/api/routes/documents.py): ingestion API · Document upload, processing, and retrieval endpoints. · `backend/app/api/routes/documents.py`
- [AI features](https://github.com/tej-carpenter/sidekick/blob/main/backend/app/api/routes/sidekick.py): feature APIs · Sidekick, insights, roadmaps, events, and diagnostics endpoints. · `backend/app/api/routes/sidekick.py`
- [Core config](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/core): security/config · Environment config and JWT/security helpers. · `backend/app/core`
- [DB layer](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/db): orm persistence · SQLAlchemy models and database connection. · `backend/app/db`
- [Schemas](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/schemas): pydantic models · Request and response contracts for API domains. · `backend/app/schemas`
- [Services](https://github.com/tej-carpenter/sidekick/tree/main/backend/app/services): business logic · Document processing, Gemini orchestration, insight generation, and vector search. · `backend/app/services`

### BFF

Small Node service entrypoint.

- [Node BFF](https://github.com/tej-carpenter/sidekick/blob/main/bff/src/server.ts): service · Auxiliary Node service entrypoint. · `bff/src/server.ts`

### Data/State

Local and database-backed runtime state.

- [Vector store](https://github.com/tej-carpenter/sidekick/tree/main/backend/chroma_data): rag index · Chroma-backed semantic retrieval for documents and sidekick QA. · `backend/chroma_data`
- [Postgres](https://github.com/tej-carpenter/sidekick/tree/main/backend/alembic): primary database · Structured application data managed by SQLAlchemy and Alembic. · `backend/alembic`
- [Uploads](https://github.com/tej-carpenter/sidekick/tree/main/backend/uploads): file store · Locally stored source documents for ingestion. · `backend/uploads`

## Connections

- Next.js app → Auth pages: routes · Auth pages live inside the app router.
- Next.js app → Dashboard pages: routes · Dashboard pages live inside the app router.
- Next.js app → Shared UI: uses · Pages compose shared UI and providers.
- Next.js app → API client: calls · Client requests are sent through the API boundary.
- API client → FastAPI app: HTTP · Frontend talks to the FastAPI backend.
- FastAPI app → API routes: mounts · Main app wires domain route modules.
- API routes → Auth/users: includes · Identity and user endpoints.
- API routes → Documents: includes · Document ingestion and retrieval endpoints.
- API routes → AI features: includes · AI-oriented feature endpoints.
- API routes → Core config: depends on · Routes use shared config and security.
- API routes → Schemas: validates · Endpoints exchange typed Pydantic payloads.
- API routes → Services: orchestrates · Routes delegate business logic to services.
- Services → DB layer: reads/writes · Application state is persisted through the ORM layer.
- Services → Vector store: retrieves · Semantic lookup for grounded answers and similarity search.
- Services → Uploads: ingests · Raw uploaded files feed document processing.
- DB layer → Postgres: persists · Primary structured storage is PostgreSQL.
- Services → Postgres: migrates · Schema evolution is managed through Alembic-backed migrations.
- Services → Core config: uses · Security and configuration are shared across services.
- AI features → Services: invokes · Sidekick, insights, roadmaps, and events rely on service logic.
- Node BFF → FastAPI app: proxies · Auxiliary Node layer can sit in front of the API.
