System Architecture

Audra Flow is an AI-native platform built on a modern, service-oriented architecture. This page covers the monorepo layout, the technology choices behind each service, how the services communicate, and how data flows through the system.

Architecture Principles

1. AI-Native — AI capabilities are embedded throughout the platform, not added as an afterthought.
2. Security-First — all data stays within the enterprise boundary with JWT-based auth, RBAC, and audit logging.
3. Process-Aware — the delivery playbook (Discovery, Definition, Design, Delivery, Release) is encoded directly into the platform.
4. Traceable — every artifact links back to its origin, providing full value traceability from goals to evidence.

Monorepo Structure

The codebase is organised as a monorepo with clearly separated applications and shared packages:

audra-flow/
├── apps/
│   ├── web/                 # Full-stack web application
│   │   ├── frontend/        # React + Vite SPA
│   │   └── backend/         # Express API + Prisma ORM
│   └── ai-service/          # Python AI microservice
├── packages/
│   ├── types/               # Shared TypeScript types
│   └── validation/          # Shared Zod validation schemas
├── infrastructure/
│   ├── infra-development/   # Docker Compose for local dev
│   └── infra-production/    # Terraform modules for AWS
├── docs/                    # Project documentation
└── scripts/                 # Utility and CI scripts

apps/web

The web application is split into a frontend (React single-page app built with Vite) and a backend (Express API that talks to PostgreSQL via Prisma). Both live under apps/web and share TypeScript types from the packages/ directory.

apps/ai-service

A standalone Python service built with FastAPI. It hosts the RAG pipeline, multi-agent orchestration (LangGraph), and the Product Guru analysis engine. It communicates with the web backend over HTTP.

packages/

Shared code extracted into npm workspace packages. This prevents type duplication between frontend and backend and ensures a single source of truth for validation schemas.

Technology Stack

Frontend

Backend

AI Service

Data & Infrastructure

Service Communication

The system uses a straightforward request/response model between three main layers:

1. Browser to Web Backend — the React SPA makes REST API calls to the Express backend over HTTPS. Authentication is handled via JWT bearer tokens on every request.
2. Web Backend to AI Service — when AI features are needed (chat, document processing, analysis), the Express backend proxies requests to the FastAPI service over an internal HTTP connection. The AI service is not exposed to the public internet in production.
3. AI Service to External Providers — the AI service calls external LLM providers (DeepSeek for completions, OpenAI for embeddings) over HTTPS. All calls are made server-side, so API keys never reach the browser.

Redis is used for cross-cutting concerns: session caching, API rate limiting, and pub/sub messaging between services.

Data Flow Overview

Data moves through the system in a clearly defined path:

Standard CRUD Flow

1. A user action in the React frontend triggers an API call.
2. The Express backend validates the request with Zod, checks permissions via RBAC middleware, and executes the database operation through Prisma.
3. PostgreSQL stores the artifact and returns the result.
4. The response is shaped and returned to the frontend, where TanStack Query caches it for subsequent reads.

AI-Assisted Flow

1. The user invokes an AI feature (e.g. Product Guru analysis, RAG chat, or artifact generation).
2. The web backend forwards the request to the AI service with the relevant project context.
3. The AI service retrieves related documents from the vector store, constructs a prompt with retrieved context, and calls the LLM.
4. The response (with citations) is returned to the backend, which persists any generated artifacts and sends the result to the frontend.

Multi-Agent System

The AI service runs a multi-agent orchestration layer powered by LangGraph. Specialised agents handle different parts of the delivery lifecycle:

The Agent Orchestrator routes requests to the appropriate agent based on the type of artifact and phase of the delivery lifecycle.

Production Deployment

In production, Audra Flow runs on AWS with the following topology:

• Compute — ECS Fargate runs both the web service and the AI service as containerised tasks behind an Application Load Balancer.
• Database — Amazon RDS hosts PostgreSQL with automated backups and failover.
• Cache — ElastiCache provides a managed Redis cluster for caching and rate limiting.
• Storage — S3 buckets handle document uploads and static assets.
• Secrets — AWS Secrets Manager stores API keys and database credentials.

All infrastructure is defined in Terraform modules, enabling repeatable, version-controlled deployments across environments.

Next Steps

• Quick Start — get the stack running locally.
• Developer Guide — learn the branching model, testing strategy, and coding conventions.
• API Reference — explore every endpoint with request and response formats.