Elite Profile Foundation

A conversational resume platform that allows professionals to create interactive profiles where visitors can discover their work through chat.

For End Users: See USERGUIDE.md for how to create and manage your profile. Product Philosophy: See CONTEXT.md for Elite's design principles, target users, and experience goals. Testing Details: See TESTS.md for comprehensive testing documentation. Coding Conventions: See CLAUDE.md for development standards and patterns.

Quick Start

Prerequisites

Setup

# Clone and configure
git clone <repo-url>
cd Elite
cp .env.example .env
# Edit .env: Add your GEMINI_API_KEY

# Start services
docker-compose up -d

# Run database migrations / initialize schema
docker-compose exec app python -m migrations.migration_runner run

# Access application
# App: http://localhost:8000
# API Docs: http://localhost:8000/docs

Development Commands

# View logs
docker-compose logs -f app

# Run tests
docker-compose exec app pytest

# Database migrations
docker-compose exec app python -m migrations.migration_runner status    # Check migration status
docker-compose exec app python -m migrations.migration_runner run       # Apply pending migrations
docker-compose exec app python -m migrations.migration_runner rollback  # Rollback last migration

# Reset database (caution: deletes all data)
docker-compose down -v && docker-compose up -d

# Stop services
docker-compose stop

Local Development Without Docker (Advanced)

If you need to run locally without Docker:

# 1. Install PostgreSQL locally (not included in repo)
# macOS: brew install postgresql@16
# Ubuntu: sudo apt-get install postgresql-16

# 2. Create database
createdb elite

# 3. Set environment variables
export DATABASE_URL="postgresql://your_user:your_pass@localhost:5432/elite"
export GEMINI_API_KEY="your_api_key"

# 4. Install dependencies
poetry install

# 5. Run migrations / initialize schema
poetry run python -m migrations.migration_runner run

# 6. Run application
poetry run uvicorn main:app --reload

Note: SQLite is no longer supported due to native UUID type usage in models.

Features Overview

See CONTEXT.md for detailed product philosophy and user personas.

Architecture

Tech Stack: - Backend: FastAPI + SQLAlchemy ORM - Database: PostgreSQL (Docker Compose for dev, Render for prod) - Frontend: Server-rendered HTML with minimal JavaScript - Auth: Session-based with JWT tokens in HTTP-only cookies - AI: Google Gemini 2.5 Flash via modular agent framework

Agent System: - BaseAgent - Abstract base with Gemini API integration and error handling - AgentRegistry - Central registry for agent instances (singleton pattern) - Specialized Agents: InterviewAgent, CurriculumVitaeImportAgent, AdvocateAgent - Reusable Tools: Timeline queries, gap detection, context formatting - Composable Prompts: Inheritance-based prompt management

Runtime Model: - GET / is a thin public landing page - GET /{username} is Elite's public profile artifact and should stay lightweight - POST /api/discovery/{username}/chat owns discovery session and AI execution - Database schema setup belongs to migrations, not request-serving app startup

Key Directories: - /agents/ - AI agent implementations - /services/ - Business logic (event, resume, auth services) - /routers/ - API endpoints and page rendering - /models/ - SQLAlchemy database models - /schemas/ - Pydantic request/response schemas - /migrations/ - Database migration files

Configuration

Environment variables (see config.py for all options):

Required: - GEMINI_API_KEY - Google Gemini API key for AI features

Optional (with defaults): - DATABASE_URL - PostgreSQL database connection - SECRET_KEY - JWT signing secret (change for production!) - GEMINI_MODEL - AI model version (default: gemini-2.5-flash) - LLM_RATE_LIMIT_CALLS - API calls per user per minute (default: 5) - TIMELINE_GAP_THRESHOLD_DAYS - Days before gaps flagged (default: 60) - SESSION_CLEANUP_HOURS - Session expiry time (default: 24)

Database

Core Tables: - users - Authentication and user identity - profiles - Public profile information (name, public tagline, DB-stored profile photo, contact links, roles, industries) - events - Timeline events (year/month, optional organization, role, what, how, why, outcomes, visibility)

Feature Tables: - interview_sessions - Interview Mode conversation state - discovery_sessions - Visitor chat sessions (24-hour expiry, anonymous) - resume_context - Parsed resume data (intermediate storage) - failed_turns - Chatbot error logging for debugging - organizations - User-scoped company/institution data with enrichment fields

Migration System:

Docker (recommended):

docker-compose exec app python -m migrations.migration_runner run       # Apply pending migrations
docker-compose exec app python -m migrations.migration_runner status    # Check migration status
docker-compose exec app python -m migrations.migration_runner rollback  # Rollback last migration

Local (without Docker):

python -m migrations.migration_runner run       # Apply pending migrations
python -m migrations.migration_runner status    # Check migration status
python -m migrations.migration_runner rollback  # Rollback last migration

See CLAUDE.md for migration conventions and patterns.

API Documentation

Interactive API documentation available at: - ReDoc: http://localhost:8000/redoc (recommended) - Swagger UI: http://localhost:8000/docs

Key Endpoints: - /api/auth/* - Authentication (signup, signin, signout) - /api/profile/* - Profile management (create, update, publish) - /api/interview/* - Interview Mode (start, send message, end) - /api/resume/* - Resume upload and management - /api/events/* - Timeline event CRUD - /api/discovery/* - Discovery Mode chat for visitors - /api/career-story - Deterministic assembled CareerStory for the authenticated owner

Testing

Comprehensive test suite with 94 tests using pytest.

Quick Commands:

pytest                    # Run all tests
pytest -v                 # Verbose output
pytest -m unit            # Unit tests only
pytest -m integration     # Integration tests only
pytest -m agent           # Agent-related tests
pytest --cov=agents       # Coverage report

Test Organization: - Unit tests: Fast, mocked dependencies - Integration tests: Real database interactions - Fixtures in tests/conftest.py (database, users, factories, mocks)

See TESTS.md for comprehensive testing guide including fixtures, patterns, and best practices.

Development

Conventions (from CLAUDE.md): - Python type hints and docstrings everywhere - Pydantic schemas in /schemas/, SQLAlchemy models in /models/ - FastAPI routers in /routers/ with clear prefixes - Service layer for business logic (avoid logic in routers) - Database changes via migrations only (never modify DB directly) - Conventional Commits for git messages

Code Style: - Python: PEP8, explicit over clever - JavaScript: Vanilla JS, progressive enhancement - CSS: No frameworks, CSS variables for design system - HTML: Semantic, server-rendered

Production Deployment

  1. Set Environment Variables: bash export GEMINI_API_KEY="your_production_api_key" export SECRET_KEY="strong_random_secret_key_at_least_32_chars" export DATABASE_URL="postgresql://user:pass@host:5432/dbname"

  2. Run Migrations: bash python -m migrations.migration_runner run

  3. Start Application: bash uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Production Checklist: - ✅ Change SECRET_KEY from default - ✅ Use PostgreSQL (not SQLite) - ✅ Configure proper CORS origins - ✅ Enable HTTPS - ✅ Set up monitoring and logging - ✅ Configure backup strategy for database

Documentation Map

License

[Add license information if applicable]