Project Map
This page is the quick index for the whole repository. Use it to find the right starting point before changing code.
Root
| Path | Purpose |
|---|---|
README.md | Setup, API overview, deployment notes, and route reference. |
AGENTS.md | Required coding conventions and definition of done. |
docs-site/docs/features.md | Current behavior ledger (Features page); update it with feature changes. |
docker-compose.yml | Local PostgreSQL with pgvector. |
start.sh / stop.sh | One-command local launcher (API + web + docs) and port cleanup. |
docs-site/ | Docusaurus maintainer documentation. |
docs/superpowers/ | Historical specs and implementation plans. |
server/ | FastAPI backend, SQLAlchemy models, migrations, tests, evals. |
web/ | React frontend, Vite config, components, screens, types. |
prototype/ | Original static HTML visual reference only. |
Backend
| Path | Purpose |
|---|---|
server/app/main.py | FastAPI app factory, router mounting, middleware, SPA/static serving. |
server/app/config.py | Environment settings and provider selection. |
server/app/models.py | SQLAlchemy schema source of truth. |
server/app/schemas.py | Pydantic request-body validation. |
server/app/serializers.py | Stable response DTOs. |
server/app/routers/ | HTTP endpoints grouped by domain. |
server/app/lib/ | Business logic, auth helpers, uploads, combat, AI/RAG modules. |
server/alembic/ | Database migrations. |
server/tests/ | Pytest suite. |
server/evals/ | AI evaluation harnesses. |
Frontend
| Path | Purpose |
|---|---|
web/src/App.tsx | Top-level route tree and auth gates. |
web/src/types.ts | API DTO types. |
web/src/lib/api.ts | All API calls and streaming client code. |
web/src/lib/auth.tsx | Current-user state and session handling. |
web/src/screens/ | Route-level screens. |
web/src/components/ | Shared UI and feature widgets. |
web/src/styles/tome.css | Design system and application styling. |
Generated or Local-Only Output
| Path | Purpose |
|---|---|
web/dist/ | Built SPA. |
docs-site/build/ | Built documentation site. |
docs-site/.docusaurus/ | Docusaurus cache. |
server/storage/ | Private core-rule storage. |
server/uploads/ | Public upload storage in local development. |
graphify-out/ | Generated knowledge graph output. |
Do not commit generated output unless a specific workflow says otherwise.