REACH.AI Backend

AI-powered recruitment platform backend built with FastAPI, PostgreSQL, Redis, and Celery.

Overview

This service powers candidate and employer workflows, including:

• Authentication and profile management
• Job publishing and applications
• Multi-round AI interview orchestration
• Resume screening and evaluation pipelines
• Proctoring and system-check integrations
• Async background processing for heavy/offline jobs

Tech Stack

• API: FastAPI
• Database: PostgreSQL 18 + SQLAlchemy 2.x
• Migrations: Alembic
• Queue/Worker: Celery + Redis
• Auth: JWT (python-jose) + bcrypt
• Package/Runtime: uv, Python 3.12+
• Infra (local): Docker Compose

Repository Structure

reachai-backend/
├── app/
│   ├── agents/            # AI agent modules (resume/script)
│   ├── api/               # REST + websocket routes and API helpers
│   ├── core/              # Settings, security, dependencies, logging
│   ├── crud/              # Database access layer
│   ├── db/                # Session + SQLAlchemy models
│   ├── middleware/        # Request middleware
│   ├── schemas/           # Pydantic request/response models
│   ├── services/          # Business services and integrations
│   ├── tasks/             # Celery task definitions and app config
│   └── utils/             # Shared utilities
├── alembic/               # Migration environment and versions
├── data/                  # Seed/reference datasets
├── docs/                  # Integration and operations documentation
├── guard/                 # Linux guard client source
├── scripts/               # Seed/test/support scripts
├── tests/                 # Unit/API/integration tests
├── docker-compose.yml     # Local multi-service orchestration
├── Dockerfile             # Shared image for API + worker
├── main.py                # FastAPI app entrypoint
├── pyproject.toml         # Project dependencies/config
└── .env.example           # Environment variable template

Quick Start (Docker)

1) Clone and configure

git clone https://github.com/JunaidSalim/reachai-backend.git
cd reachai-backend
cp .env.example .env

2) Build and run

docker compose up -d --build

3) Access service

• API base: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

4) Stop

docker compose down

For a full reset (including volumes):

docker compose down -v

Configuration

Use .env (copied from .env.example) for runtime settings.

Main groups:

• Database (POSTGRES_*)
• Auth/security (JWT_*, reset token settings)
• AWS S3 buckets (AWS_*)
• LLM providers and models (LLM_*, VOICE_AI_*, EVALUATION_LLM_*, SCRIPT_AGENT_*)
• System check release config (SYSTEM_CHECK_*)
• Background queue (REDIS_URL, CELERY_*)

Generate a secure JWT secret for non-local environments:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Background Jobs (Redis + Celery)

Background tasks are routed through Celery when enabled and safely fall back to in-process execution if enqueueing fails.

Primary queues:

• screening (resume screening)
• script (script pre-generation)
• media (profile embedding)
• review (independent interview review)

Detailed setup, operations, and troubleshooting:

• docs/backend-redis-celery-setup-and-ops.md

Development Commands

Run migrations:

docker compose exec backend uv run alembic upgrade head

Run focused tests:

docker compose exec backend uv run python -m pytest tests/unit/test_script_generation_runtime_guards.py tests/api/test_scripted_interview_flow.py tests/api/test_round_transcript_api.py -q

Run all tests:

docker compose exec backend uv run python -m pytest -q

API Documentation

OpenAPI docs are auto-generated by FastAPI:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

License

Proprietary software. All rights reserved.