# mitxh13/orcas architecture

> Architecture diagram of the GitHub repository mitxh13/orcas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitxh13/orcas
- Repository: https://github.com/mitxh13/orcas

## Overview

ORCAS accepts synthetic investor complaints, researches applicable SEBI/RBI rules, verifies citations, then returns a routing determination or escalates uncertain cases to a human. The graph follows that runtime workflow and includes corpus indexing, retrieval, model access, persistence, and evaluation. Relationships are based on the README and shown source/index references; unsampled service wiring is omitted where it cannot be verified.

Main entry points: [`services/worker/tasks.py`](https://github.com/mitxh13/orcas/blob/main/services/worker/tasks.py) (Worker orchestration), [`services/ingest/cli.py`](https://github.com/mitxh13/orcas/blob/main/services/ingest/cli.py) (Corpus ingestion), [`services/retrieval/app.py`](https://github.com/mitxh13/orcas/blob/main/services/retrieval/app.py) (Retrieval API), [`services/gateway/app.py`](https://github.com/mitxh13/orcas/blob/main/services/gateway/app.py) (Intake gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Complaint intake"]
  node_web["Web client<br/>[app.js]"]
  node_gateway["Intake gateway<br/>[app.py]"]
  node_guardrails["Input guardrails"]
  node_queue["Work queue<br/>[queue.py]"]
end

subgraph group_analysis["Agent analysis"]
  node_worker["Worker orchestration<br/>[tasks.py]"]
  node_researcher["Researcher agent<br/>[researcher.py]"]
  node_verifier["Citation verifier<br/>[verifier.py]"]
  node_output_filter["Output filter<br/>[output_filter.py]"]
  node_retrieval_client["Retrieval clients<br/>[retrieval.py]"]
  node_observed_retrieval["Observed retrieval"]
  node_fake_retrieval["Fake retrieval<br/>[fake_retrieval.py]"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
end

subgraph group_corpus["Regulatory corpus"]
  node_retrieval["Retrieval API<br/>[app.py]"]
  node_retrieval_service["Search and lookup<br/>[service.py]"]
  node_embedding["Local embeddings<br/>[embedding.py]"]
  node_corpus_store[("Chroma corpus store<br/>[store.py]")]
  node_ingest["Corpus ingestion<br/>[cli.py]"]
  node_metadata["Chunk metadata<br/>[metadata.py]"]
  node_chunk_ids["Chunk identifiers<br/>[ids.py]"]
end

subgraph group_platform["Runtime platform"]
  node_llm_gateway["LLM gateway<br/>[app.py]"]
  node_runstore[("Run and event store<br/>[runstore.py]")]
  node_logging["Correlated logging<br/>[logging.py]"]
  node_telemetry["Tracing and telemetry<br/>[telemetry.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Evaluation runner<br/>[run_eval.py]"]
  node_eval_metrics["Evaluation metrics<br/>[metrics.py]"]
end

node_investor(("Complaint submitter"))

node_investor -->|"submits complaint"| node_web
node_web -->|"sends complaint"| node_gateway
node_gateway -->|"validates input"| node_guardrails
node_gateway -->|"dispatches work"| node_queue
node_queue -->|"delivers task"| node_worker
node_worker -->|"runs research"| node_researcher
node_worker -->|"runs verification"| node_verifier
node_worker -->|"filters determination"| node_output_filter
node_worker -->|"records run"| node_runstore
node_researcher -->|"requests completions"| node_llm_client
node_llm_client -->|"posts chat request"| node_llm_gateway
node_researcher -.->|"uses search tools"| node_retrieval_client
node_retrieval_client -.->|"searches passages"| node_retrieval
node_observed_retrieval -.->|"calls retrieval"| node_retrieval
node_fake_retrieval -.->|"simulates retrieval"| node_retrieval
node_retrieval -->|"handles search"| node_retrieval_service
node_retrieval_service -->|"embeds queries"| node_embedding
node_retrieval_service -->|"reads chunks"| node_corpus_store
node_ingest -->|"builds metadata"| node_metadata
node_ingest -->|"embeds chunks"| node_embedding
node_ingest -->|"generates identifiers"| node_chunk_ids
node_ingest -->|"indexes chunks"| node_corpus_store
node_eval_runner -->|"scores results"| node_eval_metrics

click node_web "https://github.com/mitxh13/orcas/blob/main/services/web/static/app.js"
click node_gateway "https://github.com/mitxh13/orcas/blob/main/services/gateway/app.py"
click node_guardrails "https://github.com/mitxh13/orcas/blob/main/services/gateway/input_guardrails.py"
click node_queue "https://github.com/mitxh13/orcas/blob/main/services/gateway/queue.py"
click node_worker "https://github.com/mitxh13/orcas/blob/main/services/worker/tasks.py"
click node_researcher "https://github.com/mitxh13/orcas/blob/main/services/worker/agent/researcher.py"
click node_verifier "https://github.com/mitxh13/orcas/blob/main/services/worker/agent/verifier.py"
click node_output_filter "https://github.com/mitxh13/orcas/blob/main/services/worker/guardrails/output_filter.py"
click node_retrieval_client "https://github.com/mitxh13/orcas/blob/main/services/worker/clients/retrieval.py"
click node_observed_retrieval "https://github.com/mitxh13/orcas/blob/main/services/worker/clients/observed_retrieval.py"
click node_fake_retrieval "https://github.com/mitxh13/orcas/blob/main/services/worker/clients/fake_retrieval.py"
click node_llm_client "https://github.com/mitxh13/orcas/blob/main/services/worker/clients/llm_client.py"
click node_retrieval "https://github.com/mitxh13/orcas/blob/main/services/retrieval/app.py"
click node_retrieval_service "https://github.com/mitxh13/orcas/blob/main/services/retrieval/service.py"
click node_embedding "https://github.com/mitxh13/orcas/blob/main/services/corpus_common/embedding.py"
click node_corpus_store "https://github.com/mitxh13/orcas/blob/main/services/corpus_common/store.py"
click node_ingest "https://github.com/mitxh13/orcas/blob/main/services/ingest/cli.py"
click node_metadata "https://github.com/mitxh13/orcas/blob/main/services/ingest/metadata.py"
click node_chunk_ids "https://github.com/mitxh13/orcas/blob/main/services/corpus_common/ids.py"
click node_llm_gateway "https://github.com/mitxh13/orcas/blob/main/services/llm_gateway/app.py"
click node_runstore "https://github.com/mitxh13/orcas/blob/main/libs/orcas_common/runstore.py"
click node_logging "https://github.com/mitxh13/orcas/blob/main/libs/orcas_common/logging.py"
click node_telemetry "https://github.com/mitxh13/orcas/blob/main/libs/orcas_common/telemetry.py"
click node_eval_runner "https://github.com/mitxh13/orcas/blob/main/eval/run_eval.py"
click node_eval_metrics "https://github.com/mitxh13/orcas/blob/main/eval/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_gateway,node_guardrails,node_queue toneBlue
class node_worker,node_researcher,node_verifier,node_output_filter,node_retrieval_client,node_observed_retrieval,node_fake_retrieval,node_llm_client toneAmber
class node_retrieval,node_retrieval_service,node_embedding,node_corpus_store,node_ingest,node_metadata,node_chunk_ids toneMint
class node_llm_gateway,node_runstore,node_logging,node_telemetry toneRose
class node_eval_runner,node_eval_metrics,node_investor toneIndigo
```

## Components

### Complaint intake

- [Web client](https://github.com/mitxh13/orcas/blob/main/services/web/static/app.js): `services/web/static/app.js`
- [Intake gateway](https://github.com/mitxh13/orcas/blob/main/services/gateway/app.py): `services/gateway/app.py`
- [Input guardrails](https://github.com/mitxh13/orcas/blob/main/services/gateway/input_guardrails.py): `services/gateway/input_guardrails.py`
- [Work queue](https://github.com/mitxh13/orcas/blob/main/services/gateway/queue.py): `services/gateway/queue.py`

### Agent analysis

- [Worker orchestration](https://github.com/mitxh13/orcas/blob/main/services/worker/tasks.py): `services/worker/tasks.py`
- [Researcher agent](https://github.com/mitxh13/orcas/blob/main/services/worker/agent/researcher.py): `services/worker/agent/researcher.py`
- [Citation verifier](https://github.com/mitxh13/orcas/blob/main/services/worker/agent/verifier.py): `services/worker/agent/verifier.py`
- [Output filter](https://github.com/mitxh13/orcas/blob/main/services/worker/guardrails/output_filter.py): `services/worker/guardrails/output_filter.py`
- [Retrieval clients](https://github.com/mitxh13/orcas/blob/main/services/worker/clients/retrieval.py): `services/worker/clients/retrieval.py`
- [Observed retrieval](https://github.com/mitxh13/orcas/blob/main/services/worker/clients/observed_retrieval.py): `services/worker/clients/observed_retrieval.py`
- [Fake retrieval](https://github.com/mitxh13/orcas/blob/main/services/worker/clients/fake_retrieval.py): `services/worker/clients/fake_retrieval.py`
- [LLM client](https://github.com/mitxh13/orcas/blob/main/services/worker/clients/llm_client.py): `services/worker/clients/llm_client.py`

### Regulatory corpus

- [Retrieval API](https://github.com/mitxh13/orcas/blob/main/services/retrieval/app.py): `services/retrieval/app.py`
- [Search and lookup](https://github.com/mitxh13/orcas/blob/main/services/retrieval/service.py): `services/retrieval/service.py`
- [Local embeddings](https://github.com/mitxh13/orcas/blob/main/services/corpus_common/embedding.py): `services/corpus_common/embedding.py`
- [Chroma corpus store](https://github.com/mitxh13/orcas/blob/main/services/corpus_common/store.py): `services/corpus_common/store.py`
- [Corpus ingestion](https://github.com/mitxh13/orcas/blob/main/services/ingest/cli.py): `services/ingest/cli.py`
- [Chunk metadata](https://github.com/mitxh13/orcas/blob/main/services/ingest/metadata.py): `services/ingest/metadata.py`
- [Chunk identifiers](https://github.com/mitxh13/orcas/blob/main/services/corpus_common/ids.py): `services/corpus_common/ids.py`

### Runtime platform

- [LLM gateway](https://github.com/mitxh13/orcas/blob/main/services/llm_gateway/app.py): `services/llm_gateway/app.py`
- [Run and event store](https://github.com/mitxh13/orcas/blob/main/libs/orcas_common/runstore.py): `libs/orcas_common/runstore.py`
- [Correlated logging](https://github.com/mitxh13/orcas/blob/main/libs/orcas_common/logging.py): `libs/orcas_common/logging.py`
- [Tracing and telemetry](https://github.com/mitxh13/orcas/blob/main/libs/orcas_common/telemetry.py): `libs/orcas_common/telemetry.py`

### Evaluation

- [Evaluation runner](https://github.com/mitxh13/orcas/blob/main/eval/run_eval.py): `eval/run_eval.py`
- [Evaluation metrics](https://github.com/mitxh13/orcas/blob/main/eval/metrics.py): `eval/metrics.py`

### Other components

- **Complaint submitter**

## Connections

- Complaint submitter → Web client: submits complaint (evidence: `README.md`)
- Web client → Intake gateway: sends complaint (evidence: `README.md`)
- Intake gateway → Input guardrails: validates input (evidence: `services/gateway/app.py`)
- Intake gateway → Work queue: dispatches work (evidence: `README.md`)
- Work queue → Worker orchestration: delivers task (evidence: `README.md`)
- Worker orchestration → Researcher agent: runs research (evidence: `services/worker/tasks.py`)
- Worker orchestration → Citation verifier: runs verification (evidence: `services/worker/tasks.py`)
- Worker orchestration → Output filter: filters determination (evidence: `services/worker/tasks.py`)
- Worker orchestration → Run and event store: records run (evidence: `services/worker/tasks.py`)
- Researcher agent → LLM client: requests completions (evidence: `services/worker/agent/researcher.py`)
- LLM client → LLM gateway: posts chat request (evidence: `services/worker/clients/llm_client.py`)
- Researcher agent → Retrieval clients: uses search tools
- Retrieval clients → Retrieval API: searches passages
- Observed retrieval → Retrieval API: calls retrieval
- Fake retrieval → Retrieval API: simulates retrieval
- Retrieval API → Search and lookup: handles search (evidence: `services/retrieval/app.py`)
- Search and lookup → Local embeddings: embeds queries (evidence: `services/retrieval/service.py`)
- Search and lookup → Chroma corpus store: reads chunks (evidence: `services/retrieval/service.py`)
- Corpus ingestion → Chunk metadata: builds metadata (evidence: `services/ingest/cli.py`)
- Corpus ingestion → Local embeddings: embeds chunks (evidence: `services/ingest/cli.py`)
- Corpus ingestion → Chunk identifiers: generates identifiers (evidence: `services/ingest/cli.py`)
- Corpus ingestion → Chroma corpus store: indexes chunks (evidence: `services/ingest/cli.py`)
- Evaluation runner → Evaluation metrics: scores results (evidence: `eval/run_eval.py`)