Career Copilot (ccp-mainbuild-v1)
Career Copilot is a FastAPI + Supabase platform for recruitment discovery, trust-gated data promotion, deterministic eligibility computation, and user notifications.
Repository layout
app/backend/ — FastAPI backend and deterministic eligibility logic.app/supabase/migrations/ — SQL schema and policy migration history.app/frontend/ — React frontend.docs/ — engineering/product/domain documentation.memory/ — internal notes and planning artifacts.
Local setup and run
Backend
- Create a Python environment (Python 3.12 recommended).
- Install dependencies:
cd app/backend && pip install -r requirements.txt
- Configure environment variables in
app/backend/.env (at minimum Supabase URL, anon key, and service role key used by backend configuration).
- Start the API:
cd app/backend && uvicorn server:app --reload --port 8000
- Open:
- Swagger UI:
http://localhost:8000/docs
- ReDoc:
http://localhost:8000/redoc
Tests
From app/backend:
- Full test run:
pytest
- Coverage gate (CI parity):
pytest --cov=app --cov-fail-under=60
- Targeted suite used during runbook implementation:
pytest tests/test_error_utils.py tests/test_eligibility_mapper.py tests/test_recompute_queue_behaviour.py
- Scraper trust-gate focused suites:
pytest tests/test_admin_queue.py tests/test_scrape_runner_promote.py tests/scraping/test_extractor_json_repair.py
- Dependency vulnerability check:
Architecture overview
The backend runs as a FastAPI app (app/backend/server.py) with /api routers for auth, eligibility, notifications, admin scrape/trust, payments, canonical APIs, and the remaining placeholder compatibility router. It uses Supabase REST (via supabase-py) and optional asyncpg pool health checks. Primary runtime wiring is in server.py lifespan and router registration.
Background scheduler (APScheduler)
The in-process scheduler (notifications dispatcher + eligibility-recompute worker) is gated by the ENABLE_SCHEDULER env var.
- Dev / test / CI: leave it unset (or
false). The API still serves requests; only the cron loop is skipped, so local boots don't hammer Supabase.
- Production: set
ENABLE_SCHEDULER=true on the backend process so notification dispatch and recompute runners actually fire. Run exactly one instance with the flag on — APScheduler is in-process, not distributed.
Key backend modules:
- API routers:
app/backend/app/api/*
- Eligibility engine (pure deterministic logic):
app/backend/app/eligibility/engine.py
- Eligibility orchestration/DB I/O:
app/backend/app/eligibility/runner.py
- Profile mapping for eligibility input:
app/backend/app/profile/eligibility_mapper.py
- DB helpers/clients:
app/backend/app/db/*
- Notification recompute and scheduling:
app/backend/app/notifications/*
- Scraper + trust/ingestion pipeline:
app/backend/app/scraping/*
Data flow (scrape to user-visible outcomes)
- Scrape ingestion
- Scraper and extraction paths gather recruitment-like records.
- Trust-gate queue
- Scraped records enter admin review workflows before promotion.
- No auto-approval invariant: items remain pending/duplicate until explicit admin review and promotion.
- Promotion to recruitments/posts
- Approved records become recruitments/posts with criteria.
- Eligibility recompute trigger
- User/profile or criteria changes enqueue recompute jobs.
- Deterministic eligibility computation
- Runner loads user/profile + criteria and invokes engine.
- Result persistence + alerts
- Results saved in
eligibility_results; notifications can be upserted.
Key tables (confirmed from migration themes and backend usage)
profilesrecruitmentspostseligibility_resultseligibility_recompute_queuenotification_alertsscrape_queuetracked_recruitmentsaspirant_preferencesaspirant_educationaspirant_certificationsaspirant_exam_attemptsaspirant_exam_credentials
For migration-by-migration guidance, see docs/reference/MIGRATIONS.md.
API documentation
- OpenAPI is generated by FastAPI at runtime from route declarations and docstrings.
- Use
/docs during local development to inspect request/response examples.
- Eligibility endpoints are in
app/backend/app/api/eligibility.py.
Runbook progress
- Step 1: Consolidate common helpers — completed.
- Step 2: Improve error propagation — completed.
- Step 3: Introduce asynchronous APIs — completed.
- Step 4: Enhance documentation — completed in this change.
- Step 5: Add unit and integration tests — completed in this change.
- Step 6: Optimize queue queries — completed in this change.
- Step 7: Security and permissions — completed in this change.
- Optional event-driven architecture: not started in this change.
Frontend prototype build gate
Prototype routes are build-gated by REACT_APP_ENABLE_PROTOTYPE:
REACT_APP_ENABLE_PROTOTYPE=false (recommended for production) excludes /prototype/* route code from the build, so prototype modules are removed from shipped bundles.REACT_APP_ENABLE_PROTOTYPE=true keeps prototype routes available and lazy-loads them as on-demand chunks.
