> ## 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.

# Codebase Map and Change Ownership

> How to find the right Alleato owner for a product, data, integration, or AI change.

This page is the practical map for deciding where a change belongs. It is not a
replacement for the technical repository inventory; it is the short version a
leader or new contributor can use to orient quickly.

## Current shape

The generated system map currently records:

| Surface                  | Current inventory |
| ------------------------ | ----------------: |
| Product routes           |               333 |
| API endpoints            |               762 |
| AI tools                 |               107 |
| Curated database entries |               480 |

These values are generated from the repository, not manually maintained. The
technical map is regenerated whenever the relevant application surface changes.

## Where a change belongs

| If the change is about…                                                      | Primary owner                        | Typical location                                                       |
| ---------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
| A screen, form, table, or user journey                                       | Product application                  | `frontend/src/app`, `frontend/src/components`, `frontend/src/features` |
| An app-facing read/write API                                                 | Product application service boundary | `frontend/src/app/api`, shared `frontend/src/lib` services             |
| A database table, migration, permission, or RPC                              | Data contract                        | `supabase/migrations` and generated database types                     |
| Ingestion, Microsoft/Fireflies sync, OCR, embedding, or scheduled processing | Operational engine                   | `backend/src/services`                                                 |
| In-product AI chat, tools, retrieval, or confirmed actions                   | Product AI runtime                   | `frontend/src/app/api/ai-assistant/chat`, `frontend/src/lib/ai`        |
| A backend specialist or research workflow                                    | Specialist services                  | `backend/src/services/agents`                                          |
| A standalone agent workspace                                                 | Agent workspace                      | `agents`                                                               |

## How AI navigates the codebase

AI agents do not rely on a giant database dump or an embedding of every file.
They follow a small, layered set of maintained artifacts:

1. Repository rules and verification gates.
2. Shared domain vocabulary and invariants.
3. Generated system, route, API, and tool maps.
4. Curated database metadata that explains purpose, ownership, and known traps.
5. The smallest relevant source files, tests, migrations, and runtime evidence.

This matters because a technically valid change can still be wrong if it lands
in the wrong runtime, bypasses a shared contract, or duplicates an existing
owner.

## Keeping the map current

| Change                                 | Required update                                           |
| -------------------------------------- | --------------------------------------------------------- |
| Route, API, or AI tool                 | `npm run map:project`, then `npm run map:system`          |
| Database meaning or ownership          | Update `tables.yaml`, then `npm run db:inventory`         |
| Schema or migration                    | Regenerate database types and verify the migration ledger |
| Runtime ownership or domain definition | Update the relevant architecture guide or domain context  |

Pre-commit and CI checks detect stale generated maps. A failed check explains
the exact command needed to regenerate the artifact.

## Why this matters

The map makes impact and ownership visible before a change is made. That lets
Alleato scale without creating parallel implementations, undocumented data
paths, or AI behavior that only exists in an individual developer's memory.

## Further reading

* [Architecture Overview](/architecture/overview)
* [AI Platform](/architecture/ai-platform)
* [Generated technical system map](https://github.com/The-Alleato-Group/project-management/blob/main/docs/architecture/SYSTEM-MAP.md)
* [AI-readable codebase guide](https://github.com/The-Alleato-Group/project-management/blob/main/docs/architecture/AI-READABLE-CODEBASE.md)