Backend

Owner: Backend Engineering Last reviewed: 2026-Q2

The backend is a FastAPI application with async SQLAlchemy, PostgreSQL, Alembic migrations, and integrations with Azure services (OpenAI, Vision, Document Intelligence, Blob Storage). Authentication uses Clerk JWT verification with a dual model for authorization.

Key Paths

• backend/py/main.py – app factory, CORS, security headers, router registration, root index.
• backend/py/api/routes/* – route modules grouped by domain (kanban, board permissions, action-point sharing, comments, users, notifications, embeddings, document sharing, vector documents, workflows, webhooks, health) plus Azure-specific routes (AI, AI Vision, Blob Storage, Document Intelligence).
• backend/py/schemas/* – Pydantic request/response models shared by routes.
• backend/py/models/base.py – SQLAlchemy 2.x ORM models.
• backend/py/db/database.py – async engine/session config; TLS for Azure.
• backend/py/core/* – authN/Z helpers, config, error types.
• backend/py/services/* – service layer (kanban, storage, AI integrations, workspace provisioning, v2 document pipeline).
• backend/py/alembic/* – migration env and versions.

Authentication

• Verify Clerk JWT via JWKS (RS256) with caching (core/authentication.py).
• Validate issuer and (optionally) azp via CLERK_AUTHORIZED_PARTIES.
• Dual model (ADR-001): use ClerkUser (claims) and JIT-provisioned local User (DB) via get_current_db_user.

Authorization

• Board access: board owner or explicit BoardPermission grant.
• Action-point access: owner, direct ActionPointShare, or board-based access through ActionPointBoardAssociation.
• Use helpers in core/authorization.py; do not rely on client-side permission hints.

Data Model Highlights

• Kanban: Board, Column, ActionPoint, ActionPointBoardAssociation (per-board column_id + lexorank position).
• Collaboration: BoardPermission, ActionPointShare, Comment, Attachment, Tag, ActionPointTag, BoardTag, LinkedActionPoint.
• Identity/workspace: User, Organization, Role, UserRole.
• Documents: Document, DocumentChunk, DocumentPermission (with PermissionLevel), audit logging.
• AI: BotInteraction, BotGeneratedActionPoint.

Document & AI Services

• Upload gating: sizes, MIME, extension allow-list in core/config.py.
• Azure Blob storage for persistence; time-limited SAS for direct upload/download.
• AI pipelines: services for adaptive chunking, async document processing, embeddings, and querying (LlamaIndex, pgvector integration).

API Contracts

• OpenAPI exposed by FastAPI; keep schemas/* authoritative for shapes.
• When changing routes, update examples/validation and notify frontend to regenerate clients.

Migrations & Testing

• Migrations: Alembic; prefer additive, backward-compatible changes.
• Tests: backend/py/tests/* with pytest/pytest-asyncio. Favor pure service tests for logic and limited route tests for wiring.

Error Handling & Health

• Centralized errors in core/errors.py; prefer typed exceptions → HTTP responses.
• Health endpoints at /health/* for liveness, readiness, metrics.

Performance

• Use async DB IO, indexes, selective columns.
• Batch external API calls; prefer background work for heavy tasks when available.
• Paginate list endpoints by default.

Local Dev

• Create .env from backend/py/env.example with DB, Clerk, and Azure values.
• Run from backend/py: python main.py.