System Design

Site Map

The platform is a single-page application with six distinct routes, a floating chat widget accessible from every page, and eight individual vulnerability detail pages branching from the home catalogue.

Solid lines indicate direct navigation. The chat widget (dashed border) is mounted in the root layout and is accessible from every route without navigation.

1. High-Level Architecture

The platform is structured as two independently deployable processes — a React (Vite) frontend and a FastAPI backend — communicating exclusively over an HTTP REST API with a single Server-Sent Events (SSE) channel for streaming chat responses. This separation enforces a strict client/server boundary: all business logic, model access, and persistence reside in the backend; the frontend is a pure rendering and interaction layer with no direct database or LLM access.

External dependencies are confined to two integration points: the model providers (connected through Microsoft Foundry AI or custom HTTP endpoints) (used by the platform model provider and the AI analysis sub-system) and the Garak CLI (invoked as a managed subprocess for red-teaming framework runs). Both integrations are behind abstract interfaces in the domain layer, so neither affects the core business logic.

2. Design Principles & Extensibility

The central architectural decision of this platform is that every major extension point (adding a new LLM provider, a new test runner, or a new mitigation strategy) is defined by a single-method abstract base class in the domain layer. No routing logic, service code, or API layer needs to change. The entire system is open for extension and closed for modification.

Three Core Interfaces

The domain layer defines exactly three abstract base classes. Together they cover every way the platform interacts with external models and applies security controls.

class ModelProvider(ABC):

  @abstractmethod
  async def generate(
    self,
    request: ModelRequest
  ) -> ModelResponse:
    """Execute a model call."""
    pass

class TestRunner(ABC):

  @abstractmethod
  async def run(
    self,
    test: Test,
    prompt: Message | None
  ) -> TestResult:
    pass

class Mitigation(ABC):
  layer: MitigationLayer

  @abstractmethod
  def apply(
    context: MitigationContext
  ) -> MitigationContext:
    pass

What Extensibility Looks Like in Practice

Because all business logic is written against these interfaces, and never against concrete classes, every extension requires changes in exactly one place.

Supporting Architectural Patterns

Three further patterns work together to keep the interfaces clean and the system testable end-to-end.

Dependency Rule Visualised

An arrow from layer A to layer B means "A imports B". The domain layer — where all three interfaces live — is at the centre and has no outward arrows.

3. Frontend Architecture

The frontend is a React 18 single-page application built with Vite and React Router v7. It is organised around six top-level pages, each a dedicated TypeScript module under app/pages/, backed by shared shadcn/ui components and a floating chat widget accessible from every page. All LLM-facing and persistence operations are delegated to the backend; the frontend holds no persistent state beyond React component state and browser localStorage (chat history).

Key Frontend Subsystems

Shared TypeScript types serve as the interface contract between frontend and backend. Every REST response is typed against these definitions, ensuring that any backend schema change propagates as a compile-time type error rather than a silent runtime failure.

4. Backend Layered Architecture

The backend is decomposed into four layers. Each layer is a distinct Python package under src/, and the dependency rule is enforced by import discipline: no module in an inner package may import from an outer one.

Layer Responsibilities

Model and Mitigation Registries

The infrastructure layer exposes two module-level dictionaries that act as service locators for pluggable strategies. MODEL_REGISTRY maps model identifiers (e.g. "gpt-5.2") to ModelProvider instances; MITIGATION_REGISTRY maps slug strings (e.g. "pre_filter") to Mitigation instances. Both registries are populated at module import time, making new providers and mitigations addable without modifying any service code.

5. Database Architecture

The backend uses a single SQLite database file at sqlite:///./app.db, accessed via SQLAlchemy ORM and initialised at startup with Base.metadata.create_all(bind=engine). Persisted storage is deliberately narrow: only user-generated artefacts are written to disk. The platform's security knowledge base is held separately in backend code as in-memory registries.

There are no foreign keys in the schema because each stored record is designed to be self-contained. A test row already includes its model, environment, and runner payloads; a prompt enhancement row already includes its selected mitigations and verification result. For a single-user SQLite-backed educational platform, this is a pragmatic tradeoff: simpler CRUD operations, no joins for common reads, and a domain model that evolves more quickly than the SQL schema.

How Vulnerabilities and Mitigations Are Stored

The vulnerability catalogue and mitigation knowledge are not database tables. They are stored in the backend as module-level Python dictionaries populated with immutable dataclass instances when the process starts.

This split is important. SQLite stores operational artefacts created by users during normal use of the platform. By contrast, vulnerabilities and mitigations are shipped with the codebase as trusted reference content. The chat assistant queries these in-memory registries through search_knowledge_base(), which tokenises and ranks the Python-defined entries directly without any SQL query, migration, or seed data step.

The overall database architecture is therefore hybrid in practice: relational persistence for mutable workflow state plus static code-defined registries for security knowledge. Both are part of backend state management, but only the former is managed by SQLAlchemy and written to the SQLite file on disk.

6. API Design

The backend exposes a RESTful HTTP API mounted under /api/v1 with six route modules. All request and response bodies are JSON validated by Pydantic v2 schemas. The API contract is formally documented by FastAPI's auto-generated OpenAPI specification, accessible at /docs during development.

Request / Response Contract

The POST /tests/{id}/run endpoint is the most structurally complex, returning a RunResult object that varies by runner type:

The SSE endpoint at POST /chat/stream emits newline-delimited data: events. Each event carries a JSON object with a single token field. A terminal data: [DONE] event signals end-of-stream, following the SSE streaming convention standardised by Azure AI Foundry's compatible endpoints.

7. Robust Error Handling

Robustness is handled as a first-class architectural concern. The backend distinguishes between invalid user configuration, unknown mitigation setup, missing resources, and failures from external systems such as model providers or framework subprocesses. Instead of allowing these failures to crash the platform silently, each class of error is caught close to its source, converted into a controlled response, and surfaced back to the frontend with a clear failure reason.

This is especially important for external integrations. When an OpenAI-compatible endpoint, Anthropic call, Azure content filter, custom external HTTP model, or Garak framework scan fails, the backend captures the upstream failure and returns it through the API instead of swallowing it. The result is operational transparency: users can distinguish a bad prompt, a broken mitigation configuration, a missing record, and an external-system outage because each travels back through the request path with a different status code and message.