Architecture

Architecture

This section describes the current system architecture as implemented in this repo.

High-Level

Workopti high-level architecture
  • Frontend: React + TypeScript (Vite), Tailwind, Radix UI, Clerk for auth, OpenAPI-generated clients (Orval).
  • Backend: FastAPI (Python), async SQLAlchemy, PostgreSQL, Alembic, Clerk JWT verification, Azure integrations (OpenAI, Vision, Document Intelligence, Storage), OpenTelemetry.
  • Infra: Docker images built in Azure DevOps, pushed to ACR, deployed to Azure Web App for Containers; CDN/Front Door in front of frontend.

Authentication & Authorization

  • Clerk: Frontend obtains tokens via Clerk; backend verifies JWT with Clerk JWKS (see backend/py/core/authentication.py).
  • Dual model (ADR-001):
    • ClerkUser for verified Clerk identity and entitlement claims.
    • Local User for DB relationships, ownership, permissions, and sharing via JIT provisioning.
  • Use get_current_user when you only need verified Clerk identity; use get_current_db_user for DB filters and ownership checks.
  • Board and action-point access is user-scoped through ownership, BoardPermission, ActionPointShare, and board placement.

API Layer

  • Entrypoint: backend/py/main.py defines CORS, security headers, and includes routers.
  • Routers live in backend/py/api/routes/* grouped by capability (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).
  • Response/request schemas live in backend/py/schemas/.
  • OpenAPI is exported (used by frontend Orval to generate clients frontend/src/api/generated). Keep it in sync.

Data Layer

  • DB: PostgreSQL with asyncpg; async engine and sessions in backend/py/db/database.py.
  • ORM: SQLAlchemy 2.x models in backend/py/models/base.py.
  • Migrations: Alembic (backend/py/alembic/*).
  • Common entities:
    • Users: User — local DB user, JIT-provisioned on first login.
    • Boards & work items: Board, Column, ActionPoint, ActionPointBoardAssociation (junction table; per-board column and LexoRank position, allowing an action point to appear on multiple boards), LinkedActionPoint (peer links between action points).
    • Permissions & sharing: BoardPermission (explicit per-user grants on boards), ActionPointShare (cross-user sharing with snapshot and status lifecycle).
    • Tagging: Tag, ActionPointTag, BoardTag.
    • RAG / documents: Document, DocumentChunk (chunked text segments, each with a Vector(1536) pgvector embedding — the core RAG table), DocumentPermission (per-user sharing permissions on documents), DocumentAccessLog (document-specific audit trail, separate from AuditLog).
    • AI bot: BotInteraction, BotGeneratedActionPoint (log of AI bot conversations and the action points they generate).
    • Supporting: Comment, Attachment, AuditLog, Notification.
    • Legacy (deprecated): Organization, Role, UserRole, Team — these models exist in the schema for historical reasons but are not part of the active architecture. The current build uses personal accounts only; the organization/team/role hierarchy is deprecated and not used in the active permission model.
  • Vector/embeddings: DocumentChunk stores embeddings in a first-class pgvector Vector(1536) column (not a plain Postgres array). Similarity search uses the cosine-distance operator (<=>). Services in services/* handle adaptive chunking, embeddings, and vector store (e.g., adaptive_chunker_service.py, openai_embeddings_service.py, vector_store_service.py).

Document & AI Processing

  • Uploads: Size/type constrained in core/config.py; storage via Azure Blob.
  • Analysis: Azure AI Vision/Document Intelligence for OCR and structure, OpenAI (Azure) for embeddings and query workflows.
  • Pipeline: services in services/* provide adaptive chunking (adaptive_chunker_service.py), async document processing (async_document_processor.py), and vector storage (vector_store_service.py).
  • Deduplication/versioning: Document.content_hash, version and deletion flags prevent duplicates and manage lifecycle.

Health, Security, and CORS

  • Health endpoints under /health/* (liveness, readiness, metrics).
  • Security headers middleware (clickjacking, MIME sniffing, HSTS in non-dev).
  • CORS origins vary by ENVIRONMENT (prod, staging, dev) in main.py.

Frontend Architecture

  • Vite + React 19, TypeScript.
  • State/data: React Query for server state; local component state for UI interactions.
  • API client: Orval generates clients from frontend/openapi.json → src/api/generated. Thin wrappers in src/api/* and src/lib/api.ts.
  • Auth: Clerk React SDK (src/config/clerk.ts), user sync overlay/gate to ensure backend JIT provisioning.
  • UI: Tailwind v4, Radix primitives, shadcn-inspired components under src/components/ui.
  • Feature example: Kanban board uses @dnd-kit for drag/drop; board/action-point endpoints live under /api/kanban.

Deployment Topology

  • Azure DevOps pipelines:
    • API: azuredevops/pipelines/api.yaml → Docker build → ACR → Azure Web App for Containers (per dir, e.g., py).
    • Frontend: azuredevops/pipelines/frontend.yaml → Docker build → ACR → Azure Web App for Containers → Front Door cache purge.
  • Environments: dev and showcase active; prod config present but commented. Variable groups per branch.
PrinciplesTech Stack