Backend Overview - Webyes Auditor

What is the Backend?

The auditor-backend is a FastAPI application that serves as the single API for both frontend apps. It handles authentication, website management, audit orchestration, billing, RUM, reports, and all business logic.

Framework

FastAPI on Python 3.12 · Uvicorn ASGI server

Database

PostgreSQL via SQLAlchemy 2 (async) · asyncpg driver · Alembic migrations

Cache

Redis via aioredis — sessions, permission cache, scan status

Auth

JWT RS256 · Google OAuth · Microsoft OAuth · AWS Cognito

Payments

Stripe — subscriptions, checkout, webhooks

AI

Google Gemini 2.0 Flash — accessibility fix generation

URL	Purpose
`http://localhost:8000`	API base (dev)
`http://localhost:8000/api/openapi.json`	Swagger / OpenAPI spec

Project Structure

auditor_app/ — Application core:

web/ — HTTP layer

Path	Purpose
`web/application.py`	FastAPI app factory (`get_app`) — registers middleware, mounts routers
`web/lifetime.py`	Startup & shutdown event handlers
`web/api/router.py`	Master router — mounts all sub-routers under `/api`
`web/api/auth/`	Login, logout, OAuth callbacks (Google, Microsoft, Cognito)
`web/api/user/`	Registration, profile, invites, email verification
`web/api/website/`	Website CRUD — add, update, delete, search
`web/api/website_audit/`	Scan management — start, cancel, history, status
`web/api/accessibility/`	WCAG audit data — receive from scanner, serve to frontend
`web/api/results/`	Aggregated audit result retrieval
`web/api/report/`	Report generation — on-demand and scheduled
`web/api/solutions/`	Gemini AI-powered fix suggestions
`web/api/stripe/`	Billing — checkout, subscriptions, webhooks
`web/api/organisation/`	Organisation CRUD and member management
`web/api/plan/`	Subscription plan listing
`web/api/scan_schedule/`	Recurring scan schedules
`web/api/uptime_monitor/`	Uptime monitor create/read/update/delete
`web/api/search_console/`	Google Search Console OAuth + data
`web/api/rum/`	Real User Monitoring metrics and config
`web/api/region/`	Available scan server regions
`web/api/monitoring/`	Health check endpoint
`web/api/offboarding/`	Account deletion and cancellation
`web/api/wy_admin/`	Internal admin endpoints

db/ — Data layer

Path	Purpose
`db/base.py`	SQLAlchemy declarative base
`db/dependencies.py`	`get_db_session()` FastAPI dependency
`db/models/`	30 ORM model classes
`db/dao/`	35 Data Access Objects (one per model)
`db/migrations/`	Alembic revision files

services/ — Business logic

Path	Purpose
`services/redis/`	Redis connection pool lifecycle
`services/solutions/`	Gemini AI prompt builders for each issue type

utils/ — Shared utilities

File	Purpose
`jwt_functions.py`	JWT create / verify / refresh
`stripe_functions.py`	Stripe API wrappers
`aws_functions.py`	S3 upload · presigned URLs · SES email
`email_sms_functions.py`	Mailersend and Resend email sending
`cognito_jwt.py`	AWS Cognito JWKS validation
`slack_functions.py`	Internal Slack notifications
`rate_limiter.py`	SlowAPI limiter instance
`user_permission_functions.py`	Role-based permission checks
`common_functions.py`	General helpers

Root-level files:

File	Purpose
`auditor_app/__main__.py`	Entrypoint — configures and starts Uvicorn
`auditor_app/settings.py`	All config via pydantic-settings + env vars
`auditor_app/logging.py`	Loguru structured logging setup
`alembic.ini`	Alembic migration config
`cert/private.key`	RSA private key — signs JWT tokens
`cert/public.key`	RSA public key — verifies JWT tokens
`pyproject.toml`	Poetry dependencies
`deploy/`	Deployment configs (Docker, K8s, etc.)

Application Startup Lifecycle

Entrypoint

python -m auditor_app calls uvicorn.run() with factory=True, pointing at auditor_app.web.application:get_app.

App factory runs

get_app() creates the FastAPI instance, registers CORSMiddleware and SessionMiddleware, then mounts the master router at /api.

Database pool created

An async SQLAlchemy engine is created with pool_size=20, max_overflow=10. A session factory is stored on app.state.

OpenTelemetry initialised

If AUDITOR_APP_OPENTELEMETRY_ENDPOINT is set, FastAPI, SQLAlchemy, and Redis instrumentation is activated and connected to the OTLP exporter.

Redis pool created

An async Redis connection pool is created and stored on app.state.redis_pool.

Redis cache warmed

Four datasets are loaded from PostgreSQL and cached in Redis on every restart: role→permission mappings, accessibility audit rules, scan regions, and uptime monitor API tokens.

On shutdown: database pool disposed → Redis connections closed → OpenTelemetry flushed.

Configuration

All settings live in auditor_app/settings.py using pydantic-settings. Every field maps to an environment variable prefixed with AUDITOR_APP_. Copy .env.sample → .env and fill in your values. Key variables for local dev:

AUDITOR_APP_HOST=127.0.0.1
AUDITOR_APP_PORT=8000
AUDITOR_APP_RELOAD=True
AUDITOR_APP_ENVIRONMENT=dev

AUDITOR_APP_DB_HOST=localhost
AUDITOR_APP_DB_PORT=5432
AUDITOR_APP_DB_USER=admin
AUDITOR_APP_DB_PASS=admin
AUDITOR_APP_DB_BASE=auditor_dev

AUDITOR_APP_REDIS_HOST=localhost
AUDITOR_APP_REDIS_PORT=6379

AUDITOR_APP_PRIVATE_KEY_FILE_PATH=cert/private.key
AUDITOR_APP_PUBLIC_KEY_FILE_PATH=cert/public.key
AUDITOR_APP_ALGORITHM=RS256

See the dev setup guide for the full variable reference.

Middleware Stack

Middleware	Purpose
`CORSMiddleware`	Allows all origins, credentials, methods, and headers
`SessionMiddleware`	Server-side session support (required for OAuth flows)
SlowAPI	Per-IP rate limiting on auth and registration endpoints

Dependency Injection Pattern

FastAPI’s Depends() injects these into every route handler that needs them:

@router.get("/")
async def get_websites(
    db: AsyncSession = Depends(get_db_session),      # DB session per request
    redis_pool = Depends(get_redis_pool),            # Redis connection pool
    current_user: dict = Depends(verify_token),      # Decoded JWT payload
):
    ...

Two auth dependencies are available:

Dependency	Requires
`verify_token`	Valid, non-expired JWT in Redis
`verify_token_needs_email_verification`	Valid JWT and `email_verified = True`

DAO Pattern

All database queries go through DAO classes in db/dao/. Route handlers must never contain raw SQLAlchemy queries.

from auditor_app.db.dao.website_dao import WebsiteDAO

websites = await WebsiteDAO().get_by_org_id(
    db, org_id=current_user["organisation_id"]
)

Running Alembic Migrations

# Apply all pending migrations
poetry run alembic upgrade head

# Create a migration after changing a model
poetry run alembic revision --autogenerate -m "add_website_rum_status"

# Roll back one migration
poetry run alembic downgrade -1

# Check current state
poetry run alembic current

Migration files live in auditor_app/db/migrations/versions/.

​What is the Backend?

Framework

Database

Cache

Auth

Payments

AI

​Project Structure

​Application Startup Lifecycle

​Configuration

​Middleware Stack

​Dependency Injection Pattern

​DAO Pattern

​Running Alembic Migrations