Repository Structure

/
├── .env.example            # Template for environment variables
├── requirements.txt        # Python dependencies (including test deps)
├── pytest.ini              # Pytest configuration
├── render.yaml             # Render infrastructure-as-code
├── app/                    # Main Application code
│   ├── agents/             # LangGraph state machines (Teacher Agent)
│   ├── api/                # FastAPI Routers
│   │   └── routers/        # Specific logic for chat, wallet, admin, etc.
│   ├── core/               # App configuration, auth, dependencies, logging
│   ├── models/             # Pydantic models for DB entities (billing, ingestion)
│   ├── schemas/            # Pydantic request/response schemas (chat, auth, etc.)
│   ├── services/           # Business logic / Service integrations
│   │   └── scrapers/       # Source-specific scraping logic (koutoubi)
│   └── main.py             # Application entry point
├── tests/                  # Test Suite (148 tests)
│   ├── conftest.py         # Shared fixtures, mocks, TestClient setup
│   ├── test_health.py      # Health endpoint test
│   ├── services/           # Service unit tests (8 files)
│   ├── routers/            # Router integration tests (9 files)
│   └── agents/             # Agent node function tests (1 file)
├── db/                     # SQL Scripts
│   ├── bootstrap.sql       # Full schema for new installs
│   └── migrations/         # Versioned database changes (20 migrations)
├── docs/                   # System Documentation (MkDocs)
├── postman/                # API Collection and Environments
└── scripts/                # Development and Utility scripts

Key Files

File	Purpose
app/core/config.py	Settings loaded from .env via pydantic-settings.
app/core/auth.py	JWT verification, admin auth, get_service_client().
app/core/dependencies.py	Singleton service instances (dependency injection).
app/agents/teacher_agent.py	LangGraph workflow: check_wallet -> retrieve/clarify -> finalize.
app/services/llm.py	GPT-4o answer generation with exercise detection and hint levels.
app/services/wallet_reservation.py	Reserve/finalize atomic billing + top-up.
app/services/retrieval_pipeline.py	Full retrieval pipeline: embed -> Pinecone -> rerank -> fetch chunks.
app/services/embedding_service.py	OpenAI embeddings with Pinecone upsert and refs tracking.
app/services/pinecone_adapter.py	Pinecone client wrapper (lightweight metadata, no full text).
tests/conftest.py	Library-level mocks for Supabase/OpenAI/Pinecone before app import.

Registered Routers (in app/api/router.py)

Router	Prefix	Domain
auth.py	/auth	Authentication (signup, signin, logout)
me.py	/me	User profile (GET/PATCH)
chat.py	/	Chat endpoint with streaming
curriculum.py	/curriculum	Subjects, textbooks, textbook detail
admin.py	/admin	User management, ingestion, references, stats
wallet.py	/wallet	Balance, reservations, top-up, transactions
scraping.py	/scraping	Scraper sync, runs, references

Note: quiz.py exists as a stub but is not registered in the router.