> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conformly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Overview

> Architecture and features of the Conformly.ai backend API

<style>
  {`
      p, li {
        text-align: justify;
        text-justify: inter-word;
      }
    `}
</style>

## Overview

The Conformly.ai backend (`conformly-core`) is a FastAPI-based REST API that provides AI-powered automotive compliance analysis. It supports multiple industry standards including **ASPICE**, **ISO 26262**, **ISO/SAE 21434**, and more.

The backend runs on port 8000 locally (via Docker Compose) and is deployed at `beta-api.conformly.ai` in production.

***

## Key Features

| Feature                       | Description                                                               |
| ----------------------------- | ------------------------------------------------------------------------- |
| **Multi-Standard Compliance** | Simultaneous evaluation against ASPICE, ISO 26262, ISO 21434              |
| **AI-Powered Analysis**       | LangGraph-based workflows with multimodal document processing             |
| **Visual Evidence**           | Automated highlighting and bounding-box grounding for audit trails        |
| **Workspace Management**      | Multi-tenant workspace organization with RLS isolation                    |
| **Document Processing**       | PDF parsing with OCR, structure analysis, and artifact extraction         |
| **Subscription Management**   | Stripe-integrated payment flow with free/pro/consultant plans             |
| **Background Processing**     | Celery + Redis for async task execution (up to 30 min timeout)            |
| **Real-time Updates**         | Supabase Realtime for progress tracking without polling                   |
| **Branded Emails**            | Custom HTML templates for Supabase confirmation and password reset emails |

***

## Technology Stack

| Category           | Technology                                    |
| ------------------ | --------------------------------------------- |
| **Framework**      | FastAPI (Python 3.11+)                        |
| **Task Queue**     | Celery with Redis                             |
| **Database**       | Supabase (PostgreSQL) with Row-Level Security |
| **File Storage**   | Supabase Storage (S3-compatible)              |
| **AI/ML**          | LangGraph, OpenAI GPT-4o, Google Gemini       |
| **Document AI**    | LandingAI ADE, Tavily Web Research            |
| **Vector Store**   | FAISS for semantic search                     |
| **Authentication** | Supabase JWT with refresh tokens              |
| **Payments**       | Stripe (Checkout Sessions, Webhooks)          |

***

## Core Components

### API Layer

The API is organized into versioned endpoint groups under `/api/v1/`:

| Endpoint Group     | Purpose                                                        |
| ------------------ | -------------------------------------------------------------- |
| `/auth/*`          | User authentication, profile sync, and subscription activation |
| `/payments/*`      | Stripe Checkout session creation, webhook processing           |
| `/workspaces/*`    | Multi-tenant workspace CRUD                                    |
| `/standards/*`     | Compliance standards upload and management                     |
| `/work-products/*` | Engineering document upload and processing                     |
| `/analysis/*`      | Trigger and monitor compliance analyses                        |
| `/compliance/*`    | Completeness checks and checklist validation                   |
| `/traceability/*`  | Artifact and link management, gap detection                    |
| `/export/*`        | HTML/CSV/JSON report generation                                |
| `/reports/*`       | Persisted report CRUD and download                             |

**Key API Features:**

* Request/response validation with Pydantic models
* JWT authentication middleware with subscription gating (`check_active_subscription`)
* CORS configuration via `ALLOWED_ORIGINS` environment variable
* Structured error handling and logging
* Automatic OpenAPI documentation

### Services Layer

| Service                   | Responsibility                                                         |
| ------------------------- | ---------------------------------------------------------------------- |
| **AI Services**           | LangGraph workflow orchestration for compliance analysis               |
| **Completeness Analysis** | Document section validation against templates                          |
| **Checklist Validation**  | ASPICE/FuSa/Cybersecurity checklist evaluation                         |
| **Traceability Analysis** | V-Model chain detection and gap identification                         |
| **Artifact Extraction**   | AI-powered extraction of requirements, safety goals, tests             |
| **File Service**          | Document processing, PDF parsing, text extraction                      |
| **Job Service**           | Background task management with `start_worker`/`stop_worker` lifecycle |
| **Report Service**        | Report generation and export                                           |

### Task Processing

| Component              | Purpose                                                  |
| ---------------------- | -------------------------------------------------------- |
| **Celery Workers**     | Execute long-running analysis tasks (25-30 min timeout)  |
| **Celery Beat**        | Scheduled tasks (cleanup, maintenance, periodic reports) |
| **Redis**              | Message broker and result backend                        |
| **Progress Callbacks** | Real-time progress updates via Supabase Realtime         |

**Task Flow:**

1. API receives analysis request and creates job record
2. Task enqueued to Redis with job metadata
3. Celery worker picks up and executes LangGraph workflow
4. Progress callbacks update job status in real-time
5. Results persisted to Supabase; Realtime notifies frontend

***

## Authentication & Subscription

The backend handles user lifecycle through two key endpoints:

* **`POST /auth/sync`** — Called on every login. Activates the free plan for new users or migrates a pending Stripe subscription from the `pending_subscriptions` table.
* **`GET /auth/me`** — Returns the user profile with `subscription_status` and `subscription_plan` fields.

The `check_active_subscription` FastAPI dependency can be added to any endpoint to enforce that only users with `subscription_status = 'active'` can access it.

***

## Analysis Engines

The backend implements four core analysis engines:

### 1. Gap Analysis

Compares work products against standards to detect missing or insufficient content. Outputs gaps with severity (critical/high/medium/low) and actionable recommendations.

### 2. Completeness Check

Validates document structure against expected templates. Detects placeholders, TBD markers, and missing sections.

### 3. Traceability Check

Analyzes requirement flow across the V-Model lifecycle. Detects orphan artifacts, broken chains, missing evidence, and ASIL inconsistencies.

### 4. Checklist Validation

Applies organization-specific review checklists (ASPICE, FuSa, Cybersecurity). Produces pass/fail/missing/NA evaluations with evidence references.

***

## Data Model

**Core Entities:**

| Entity                   | Description                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `profiles`               | User profiles with roles (`admin`/`engineer`/`manager`/`viewer`), `subscription_status`, `subscription_plan` |
| `pending_subscriptions`  | Pre-signup Stripe payments awaiting user claim                                                               |
| `workspaces`             | Multi-tenant project containers                                                                              |
| `standards`              | Uploaded compliance standards with parsed content                                                            |
| `work_products`          | Engineering documents with processing status                                                                 |
| `compliance_analyses`    | Analysis runs with type, status, and results                                                                 |
| `compliance_gaps`        | Detected gaps with severity, status, and recommendations                                                     |
| `recommendations`        | AI-generated remediation suggestions                                                                         |
| `traceability_artifacts` | Extracted requirements, safety goals, tests                                                                  |
| `traceability_links`     | Relationships between artifacts                                                                              |

The `profiles` table is created automatically by a `handle_new_user()` database trigger when a user signs up through Supabase Auth.

***

## API Documentation

When running locally, access interactive API documentation:

* **Swagger UI**: `http://localhost:8000/docs`
* **ReDoc**: `http://localhost:8000/redoc`

***

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/authentication">
    Complete API endpoint documentation
  </Card>

  <Card title="Installation Guide" icon="download" href="/backend/installation">
    Set up the backend locally
  </Card>

  <Card title="Architecture" icon="sitemap" href="/guides/architecture">
    Full system architecture details
  </Card>

  <Card title="Review Actions" icon="clipboard-check" href="/guides/review-actions">
    Deep dive into analysis engines
  </Card>
</CardGroup>