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

# Service catalog

> Responsibilities, authority, dependencies, replicas, and failure behavior for every Tayho deployable.

# Service catalog

The qualified production topology is defined in
[`deploy/railway/topology.ts`](https://github.com/Tay-Ho/app/blob/develop/deploy/railway/topology.ts)
and the JSON profiles under
[`deploy/railway`](https://github.com/Tay-Ho/app/tree/develop/deploy/railway).
Development normally uses one API, engine, and market-data replica; production replica counts are
shown below.

## Application and projection services

| Service               | Replicas | Exposure | Authority and dependencies                                                             | Failure propagation                                                  |
| --------------------- | -------: | -------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Cloudflare frontend   |     edge | Public   | Static UI; receives public API origin only                                             | UI unavailable; protocol and backend continue                        |
| `tayho-api`           |        2 | Public   | API keys, quotas, composition of indexer/engine/live RPC, realtime fan-out; signerless | Reads/writes unavailable through product boundary; no authority lost |
| `tayho-indexer`       | 1 writer | Private  | Sole `eth_getLogs`/Ponder owner; writes isolated on-chain projection and stable views  | Indexed reads and `indexed` correlation lag; engine receipts remain  |
| `tayho-market-data`   |        2 | Private  | Normalizes authenticated outcome/order-book sources; no DB, Redis, RPC, or signer      | Oracle/attester publication pauses; existing chain state remains     |
| `tayho-migration`     | one-shot | Private  | Sole schema-owner credential; applies keeper/API grants and migrations                 | Release blocks; runtime must not self-migrate                        |
| `tayho-observability` |  managed | Private  | Prometheus/Grafana/OTLP collection                                                     | Detection degrades; transaction authority is unchanged               |

API source:
[`apps/api`](https://github.com/Tay-Ho/app/tree/develop/apps/api). Indexer source:
[`apps/indexer`](https://github.com/Tay-Ho/app/tree/develop/apps/indexer). Market-data source:
[`apps/market-data`](https://github.com/Tay-Ho/app/tree/develop/apps/market-data).

## Keeper roles

All roles use the keeper image and a distinct entrypoint. Signing roles share a two-key,
role-specific pool across their replicas; transaction selection and nonces are serialized in
PostgreSQL.

| Role         | Replicas | Signer | Allowed authority                                                                                         |
| ------------ | -------: | -----: | --------------------------------------------------------------------------------------------------------- |
| `engine`     |        2 |     No | Accept and validate signed intents/actions; own trigger/reservation lifecycle; enqueue reference jobs     |
| `relayer`    |        2 |    Yes | Execute validated orders and hard cancellation only                                                       |
| `automation` |        2 |    Yes | Permissionless TWAP, funding update, liquidation, freeze/flatten, resolution, and claim queue maintenance |
| `oracle`     |        2 |    Yes | `attestFunding` only                                                                                      |
| `attester`   |        2 |    Yes | `attestDepth` and `attestResolution` only                                                                 |
| `guardian`   |        2 |    Yes | Pause/unpause stale or unsafe markets                                                                     |
| `revenue`    |        1 |    Yes | Vault revenue `skim` only; delay tolerant                                                                 |
| `auditor`    |        1 |     No | Inspect protocol, permissions, operations, and projections; write only auditor findings/evidence/jobs     |

The source catalog and startup behavior live in
[`apps/keeper`](https://github.com/Tay-Ho/app/tree/develop/apps/keeper). `ChainService` rejects
functions outside the active role's allowlist before simulation or broadcast. Readiness also checks
chain identity, deployment linkage, signer separation, balances, and exact on-chain role assignment.

## Dependency rules

| Dependency              | Consumers                                                                                           | Prohibited consumers                                    |
| ----------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Public domain           | Frontend, API                                                                                       | Engine, indexer, market-data, all keeper roles          |
| Write RPC endpoint      | Signer-bearing keeper roles                                                                         | API, engine, indexer, market-data, auditor              |
| Read RPC quorum         | API live reads, keeper safety reads, auditor checks                                                 | SDK unless explicitly configured by integrator          |
| Log-scanning RPC        | Indexer/Ponder only                                                                                 | Every other service                                     |
| Coordination PostgreSQL | Engine and keeper roles through least-privilege identities; API control tables through API identity | Frontend, indexer, market-data                          |
| Indexer PostgreSQL      | Ponder writer and private query server                                                              | Keeper roles and API direct DB access                   |
| Redis/BullMQ            | Engine and workers; API admission/realtime                                                          | Indexer as authority, frontend                          |
| Signing key pool        | One matching signing role                                                                           | Engine, API, indexer, market-data, auditor, other roles |

## Scaling rules

* Add API replicas freely after validating shared quotas and realtime replay.
* Keep one Ponder writer per deployment schema. Scale query serving separately if needed.
* Signing-role replicas must share the exact reviewed role key pool; mismatches fail readiness.
* Revenue remains one replica because delay is acceptable.
* Auditor remains one replica and keyless.
* Scale a saturated worker only after proving PostgreSQL outbox uniqueness, signer-lane availability,
  and queue age rather than reacting to raw queue depth alone.