How tej-carpenter/sidekick works
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: routes API routes · services Services · app Next.js app · main.py FastAPI app
Components 18
Frontend
Next.js client app with auth and dashboard routes.
- Next.js app · App Router frontend for auth, dashboard, and feature pages.
frontend/src/app - Auth pages · Login and signup entry points.
frontend/src/app/(auth) - Dashboard pages · Main authenticated product surfaces.
frontend/src/app/(dashboard) - Shared UI · Reusable widgets, providers, and markdown/rendering helpers.
frontend/src/components - API client · Frontend backend-access layer.
frontend/src/lib/api.ts
Backend API
FastAPI application with domain routes, services, and persistence.
- FastAPI app · Application entrypoint wiring routes and dependencies.
backend/app/main.py - API routes · HTTP surface for auth, users, documents, events, insights, roadmaps, sidekick, and diagnostics.
backend/app/api/routes - Auth/users · JWT auth and user profile endpoints.
backend/app/api/routes/auth.py - Documents · Document upload, processing, and retrieval endpoints.
backend/app/api/routes/documents.py - AI features · Sidekick, insights, roadmaps, events, and diagnostics endpoints.
backend/app/api/routes/sidekick.py - Core config · Environment config and JWT/security helpers.
backend/app/core - DB layer · SQLAlchemy models and database connection.
backend/app/db - Schemas · Request and response contracts for API domains.
backend/app/schemas - Services · Document processing, Gemini orchestration, insight generation, and vector search.
backend/app/services
Data/State
Local and database-backed runtime state.
- Vector store · Chroma-backed semantic retrieval for documents and sidekick QA.
backend/chroma_data - Postgres · Structured application data managed by SQLAlchemy and Alembic.
backend/alembic - Uploads · Locally stored source documents for ingestion.
backend/uploads
Connections 20
- 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.