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

# Alleato Architecture Overview

> A Brandon-facing view of how Alleato's product, operational, data, and AI layers work together.

Alleato is one product with several deliberately separate operating layers. The
separation keeps the app responsive for users, lets operational work continue
reliably in the background, and makes AI behavior traceable instead of opaque.

## The platform at a glance

```text theme={null}
People using Alleato
        │
        ▼
Product application — Next.js on Vercel
Pages, forms, tables, auth-aware APIs, AI chat
        │
        ├──────────────► Supabase
        │                Records, permissions, migrations, search, audit data
        │
        ▼
Operational engine — FastAPI on Render
Ingestion, OCR, integrations, scheduled processing, intelligence compilation
        │
        ▼
Connected systems
Microsoft 365, Fireflies, Acumatica, document storage, AI providers
```

## What each layer owns

| Layer                   | What it does                                                                                         | Why it is separate                                                                         |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Product application     | The pages and workflows employees and project teams use every day.                                   | User-facing actions need clear permissions, fast feedback, and reliable error messages.    |
| Operational engine      | Long-running and scheduled work such as ingestion, OCR, source refresh, and intelligence processing. | This work must continue even when a browser tab is closed.                                 |
| Data and contract layer | Business records, authentication, permissions, migrations, and search indexes.                       | The database is the shared contract that keeps all services consistent.                    |
| AI layer                | Chat, retrieval, tools, source-backed answers, and controlled actions.                               | AI must be useful in the product while remaining reviewable, bounded, and evidence-backed. |

## How a typical request moves through the system

1. A person works in the product application—for example, reviewing a budget,
   asking Alleato a question, or updating a project workflow.
2. The application validates access and either reads/writes the shared data
   contract or invokes a focused service.
3. Long-running work moves to the operational engine, which records clear
   status and failure details instead of silently dropping work.
4. Results return to the product as visible records, source links, action
   previews, or explicit recovery guidance.

## Design principles

* **One owner per responsibility.** A user workflow, source sync, or data
  contract should have a clear primary owner.
* **Fail loudly.** Missing configuration, unavailable source data, and blocked
  actions must surface specific next steps.
* **Evidence before confidence.** AI and operational outputs should expose
  sources, run records, or verification status when the decision matters.
* **Generated facts, curated meaning.** Route and schema inventories are
  generated; ownership, purpose, and decisions are intentionally documented.

## What this means for leadership

The architecture is designed so that product work can move quickly without
turning every feature into a bespoke system. The app owns the experience,
specialized services own operational processing, and Supabase provides the
shared contract between them. AI is part of the product—not a side channel—and
is therefore held to the same standards for permissions, auditability, and
failure handling.

## Further reading

* [Codebase Map](/architecture/codebase-map)
* [AI Platform](/architecture/ai-platform)
* [Technical system map](https://github.com/The-Alleato-Group/project-management/blob/main/docs/architecture/ALLEATO-SYSTEM-MAP.md)