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

# System Architecture

> Current AlphaEngine module flow for public beta and encrypted intent evaluation.

AlphaEngine has two related paths:

1. the public beta Strategy Arena API path,
2. the encrypted on-chain intent path for protected submissions.

They share the same evaluation principles, but they are not the same runtime
surface.

<Tabs>
  <Tab title="Public beta">
    Builders use the Strategy Arena API through `api-router`. The route surface
    is implemented and documented under API.
  </Tab>

  <Tab title="Encrypted intent">
    Protected inputs move through contract events, listener workers, and the
    private operator runtime before evaluation evidence is published.
  </Tab>
</Tabs>

## Public beta path

```mermaid theme={null}
flowchart LR
  Builder["Builder or UI"]
  BFF["app-bff / thin client"]
  Router["api-router"]
  Sim["simulation-service"]
  Strategies["spot-strategies"]
  Amm["amm-math"]
  Ranking["ranking-evaluation"]

  Builder --> BFF --> Router
  Router --> Sim
  Sim --> Strategies
  Sim --> Amm
  Sim --> Ranking
  Ranking --> Sim
  Sim --> Router
  Router --> BFF --> Builder
```

The public beta starts at `api-router`. The router owns public HTTP contracts,
auth, request validation, and family dispatch. It does not own strategy math,
simulation orchestration, AMM adjustment, ranking formulas, or operator runtime
behavior.

## Canonical backend sequence

<CardGroup cols={2}>
  <Card title="Production PMF direction" icon="chart-line">
    `data-pipeline -> simulation-service -> ranking-evaluation`
  </Card>

  <Card title="Strategy logic" icon="table">
    `spot-strategies -> simulation-service`
  </Card>

  <Card title="Execution adjustment" icon="shield">
    `amm-math -> simulation-service`
  </Card>

  <Card title="Public gateway" icon="file-check">
    `api-router -> public HTTP gateway`
  </Card>
</CardGroup>

<Callout>
  `cofhe`, `listener-service`, and `alphaengine-contracts` belong to the
  encrypted intent runtime, not the public beta API surface.
</Callout>

## Encrypted intent path

```mermaid theme={null}
flowchart LR
  Builder["Builder"]
  Contract["AlphaEngineIntentController"]
  Listener["listener-service"]
  Runtime["cofhe operator runtime"]
  Sim["simulation-service"]
  Ranking["ranking-evaluation"]
  BFF["app-bff"]
  Evidence["scores + artifacts"]

  Builder --> Contract
  Contract --> Listener
  Listener --> Runtime
  Runtime --> Listener
  Listener --> Sim
  Sim --> Ranking
  Ranking --> Sim
  Sim --> Listener
  Listener --> BFF
  BFF --> Evidence
```

This path is for protected strategy inputs and on-chain lifecycle records.
`AlphaEngineIntentController` owns the contract events and state. The listener
runtime polls lifecycle logs, decrypts permitted handles through the operator
runtime, calls `simulation-service`, and records official evaluation results.

## Ownership boundaries

| Module                  | Owns                                            | Does not own                      |
| ----------------------- | ----------------------------------------------- | --------------------------------- |
| `data-pipeline`         | deterministic market data artifacts             | strategy logic                    |
| `spot-strategies`       | Pendle strategy signals and parameter semantics | portfolio orchestration           |
| `amm-math`              | execution adjustment and AMM invariants         | live transaction building         |
| `simulation-service`    | orchestration, artifacts, invariants            | public HTTP contracts             |
| `ranking-evaluation`    | utility, CapitalScore, eligibility, reports     | simulation execution              |
| `api-router`            | public API contract and dispatch                | strategy math or operator runtime |
| `alphaengine-contracts` | Solidity ABI, events, storage                   | off-chain simulation              |
| `listener-service`      | private operator polling and workers            | public API                        |
| `cofhe`                 | private operator encrypted-runtime helpers      | public thin client                |

## Design rule

Public access is endpoint-driven through `api-router`. Internal packages remain
implementation modules. Public docs should not present internal repos as the
public SDK surface.

## Related pages

<CardGroup cols={2}>
  <Card title="Private strategy evaluation flow" icon="lock" href="/architecture/private-strategy-evaluation-flow">
    Follow protected inputs through the confidential evaluation path.
  </Card>

  <Card title="Strategy lifecycle" icon="chart-line" href="/architecture/strategy-lifecycle">
    See submit, simulate, evaluate, score, evidence, and eligibility.
  </Card>

  <Card title="API overview" icon="file-check" href="/api/overview">
    Inspect the public route boundary.
  </Card>

  <Card title="Repo map" icon="table" href="/reference/repo-map">
    Map modules to ownership boundaries.
  </Card>
</CardGroup>