# Services Map

*The 18 backend services in `services/`, grouped by role in the request lifecycle.*

## Hot path — on the request path of every `/execute`

| Service  | Folder               | Port | Database          | Page                                          |
| -------- | -------------------- | ---- | ----------------- | --------------------------------------------- |
| Gateway  | `services/gateway/`  | 8000 | none (Redis only) | [Gateway](/services/hot-path/gateway.md)      |
| Identity | `services/identity/` | 8002 | `acp_identity`    | [Identity](/services/hot-path/identity.md)    |
| Registry | `services/registry/` | 8001 | `acp_registry`    | [Registry](/services/trust-layer/registry.md) |
| Policy   | `services/policy/`   | 8003 | none (OPA-local)  | [Policy](/services/hot-path/policy.md)        |
| Decision | `services/decision/` | 8004 | none (Redis only) | [Decision](/services/hot-path/decision.md)    |

The gateway runs the 11-stage middleware pipeline; the other four are consulted inline at specific stages.

## Trust layer — runtime governance plus durable record

| Service         | Folder                      | Port | Database                                                       | Page                                                        |
| --------------- | --------------------------- | ---- | -------------------------------------------------------------- | ----------------------------------------------------------- |
| Behavior        | `services/behavior/`        | 8005 | `acp_behavior`                                                 | [Behavior](/services/trust-layer/behavior.md)               |
| Audit           | `services/audit/`           | 8006 | `acp_audit`                                                    | [Audit](/services/hot-path/audit.md)                        |
| Autonomy        | `services/autonomy/`        | 8015 | `acp_autonomy`                                                 | [Autonomy](/services/trust-layer/autonomy.md)               |
| Identity Graph  | `services/identity_graph/`  | 8013 | `acp_identity_graph`                                           | [Identity Graph](/services/trust-layer/identity-graph.md)   |
| Flight Recorder | `services/flight_recorder/` | 8012 | `acp_flight_recorder`                                          | [Flight Recorder](/services/trust-layer/flight-recorder.md) |
| Forensics       | `services/forensics/`       | 8011 | reads `acp_audit`, `acp_identity_graph`, `acp_flight_recorder` | [Forensics](/services/trust-layer/forensics.md)             |

Behavior and Autonomy are inline at stages 5 and 7; the other four are post-decision (Audit at stage 10, Flight Recorder fire-and-forget, Identity Graph fire-and-forget, Forensics is read-only).

## Operations and intelligence

| Service      | Folder                   | Port            | Database                       | Page                                                                  |
| ------------ | ------------------------ | --------------- | ------------------------------ | --------------------------------------------------------------------- |
| Usage        | `services/usage/`        | 8007            | `acp_usage`                    | [Usage](/services/operations-and-intelligence/usage.md)               |
| API          | `services/api/`          | 8010            | `acp_api`                      | [API](/services/operations-and-intelligence/api.md)                   |
| Billing      | (cross-service flow)     | —               | spans audit + usage + identity | [Billing](/services/operations-and-intelligence/billing.md)           |
| Insight      | `services/insight/`      | 8014            | Redis only                     | [Insight](/services/operations-and-intelligence/insight.md)           |
| Intelligence | `services/intelligence/` | embedded module | Redis only                     | [Intelligence](/services/operations-and-intelligence/intelligence.md) |
| Learning     | `services/learning/`     | embedded module | shares `behavior_profiles`     | [Learning](/services/operations-and-intelligence/learning.md)         |
| Groq Worker  | `services/groq_worker/`  | none (worker)   | Redis only                     | [Groq Worker](/services/operations-and-intelligence/groq-worker.md)   |

Three workers (`groq_worker`, `insight_worker`, behavior baseline refresh) run alongside but are not addressable on a port.

## Counts at a glance

* **Total services**: 18 (including the cross-service Billing flow and three embedded modules).
* **Standalone application services**: 12 — what Aegis ships as separate FastAPI apps.
* **Workers without HTTP port**: 3 — `groq_worker`, `insight_worker`, plus the embedded behavior baseline refresher.
* **Postgres logical databases**: 11 — one per data-owning service plus the `acp` bootstrap database.
* **Services with no Postgres of their own**: 5 — Gateway, Decision, Policy, Forensics (read-only), Billing (cross-service).

## Reading order

A new engineer should read in this order:

1. [Gateway](/services/hot-path/gateway.md) — the entry point.
2. [Audit](/services/hot-path/audit.md) — the durable record.
3. [Decision](/services/hot-path/decision.md) — the signal combiner.
4. [Identity](/services/hot-path/identity.md) — the auth source of truth.
5. [Policy](/services/hot-path/policy.md) — the OPA Rego host.
6. [Registry](/services/trust-layer/registry.md) — the agent and tool grants.
7. [Behavior](/services/trust-layer/behavior.md) — the firewall.
8. [Autonomy](/services/trust-layer/autonomy.md) — the multi-agent contracts.

After those eight, the remaining ten are smaller and self-contained — read them as needed.

## Cross-references

* The full architecture is in [System Overview](/architecture/system-overview.md).
* The 11-stage pipeline detail is in [Gateway Pipeline](/architecture/10-stage-pipeline.md).
* A worked end-to-end example is in [Flow of a Decision](/architecture/flow-of-a-decision.md).
* The data model across services is in [Data Model](/architecture/data-model.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aegisagent.in/services/_index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.