# sandip-pathe/sira-seil-cockroach-aws architecture

> Architecture diagram of the GitHub repository sandip-pathe/sira-seil-cockroach-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sandip-pathe/sira-seil-cockroach-aws
- Repository: https://github.com/sandip-pathe/sira-seil-cockroach-aws

## Overview

SIRA helps buyers investigate needs, compare eligible products, review evidence, and obtain approval for protected actions; SEIL lets sellers maintain and publish versioned product evidence and respond to relevant opportunities. The web workspace calls a FastAPI application, which coordinates deterministic decision and qualification logic, bounded agent reasoning, durable state, and background work. The README documents these main boundaries; source-index references support several internal calls, but unsampled modules limit finer-grained wiring.

Main entry points: [`services/api/sira_api/cognitive_engine.py`](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/cognitive_engine.py) (Cognitive orchestration), [`services/api/sira_api/qualification_service.py`](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/qualification_service.py) (Product qualification), [`services/api/sira_api/service.py`](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/service.py) (Buyer workflow), [`python/persistence/qualification_repository.py`](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/qualification_repository.py) (Qualification repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_workspace["SIRA and SEIL workspaces"]
  node_webclient["API client<br/>[client.ts]"]
end

subgraph group_api["Application API"]
  node_api_routes["HTTP routes<br/>[routes.py]"]
  node_qualification_routes["Qualification routes"]
  node_seller_routes["Seller routes<br/>[seller_routes.py]"]
  node_exchange_routes["Exchange routes<br/>[exchange_routes.py]"]
  node_workflow["Buyer workflow<br/>[service.py]"]
  node_qualification["Product qualification"]
  node_seller["Seller evidence workflow<br/>[seller_service.py]"]
  node_exchange["Bilateral exchange"]
end

subgraph group_decision["Decision and agent runtime"]
  node_cognitive["Cognitive orchestration"]
  node_context["Context assembly"]
  node_agent_runtime["Cognitive runtime"]
  node_bedrock_runtime["Bedrock runtime<br/>[bedrock_runtime.py]"]
  node_tool_broker["Tool authorization<br/>[tool_broker.py]"]
  node_decision_graph["Decision graph<br/>[graph_v1.py]"]
  node_domain_evidence["Evidence pipeline"]
end

subgraph group_state["Durable state"]
  node_repositories["Workflow repositories<br/>[repositories.py]"]
  node_qualification_repo["Qualification repository"]
  node_cognitive_repo["Cognitive repository"]
  node_cockroach[("CockroachDB")]
end

subgraph group_async["Background processing"]
  node_qualification_worker["Qualification worker<br/>[qualification.py]"]
  node_changefeed["Changefeed handler<br/>[handler.py]"]
  node_aws_transport["AWS transports<br/>[aws_services.py]"]
end

node_users(("Buyer and seller"))
node_bedrock{{"Amazon Bedrock"}}
node_aws_queues["AWS queues and storage"]

node_users -->|"use"| node_workspace
node_workspace -->|"send requests"| node_webclient
node_webclient -->|"call API"| node_api_routes
node_api_routes -->|"delegate to"| node_workflow
node_qualification_routes -->|"delegate to"| node_qualification
node_seller_routes -->|"delegate to"| node_seller
node_exchange_routes -.->|"serve exchange"| node_exchange
node_workflow -.->|"orchestrate reasoning"| node_cognitive
node_cognitive -->|"assemble context"| node_context
node_cognitive -->|"request decision"| node_agent_runtime
node_agent_runtime -->|"delegate reasoning"| node_bedrock_runtime
node_bedrock_runtime -->|"invoke model"| node_bedrock
node_cognitive -->|"validate tools"| node_tool_broker
node_qualification -.->|"evaluate fit"| node_decision_graph
node_qualification -.->|"process evidence"| node_domain_evidence
node_workflow -.->|"persist workflow"| node_repositories
node_qualification -->|"persist decisions"| node_qualification_repo
node_cognitive -->|"record run"| node_cognitive_repo
node_repositories -->|"read and write"| node_cockroach
node_qualification_repo -->|"commit decisions"| node_cockroach
node_cognitive_repo -->|"commit runs"| node_cockroach
node_qualification_worker -->|"lease and persist"| node_qualification_repo
node_changefeed -.->|"publish changes"| node_aws_transport
node_aws_transport -->|"send or store"| node_aws_queues

click node_workspace "https://github.com/sandip-pathe/sira-seil-cockroach-aws/tree/main/apps/web/app/(workspace)"
click node_webclient "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/packages/api-client/src/client.ts"
click node_api_routes "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/routes.py"
click node_qualification_routes "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/qualification_routes.py"
click node_seller_routes "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/seller_routes.py"
click node_exchange_routes "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/exchange_routes.py"
click node_workflow "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/service.py"
click node_qualification "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/qualification_service.py"
click node_seller "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/seller_service.py"
click node_exchange "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/exchange_service.py"
click node_cognitive "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/cognitive_engine.py"
click node_context "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/context_assembler.py"
click node_agent_runtime "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/cognitive_runtime.py"
click node_bedrock_runtime "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/bedrock_runtime.py"
click node_tool_broker "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/tool_broker.py"
click node_decision_graph "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/decision_engine/graph_v1.py"
click node_domain_evidence "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/domain/evidence_pipeline.py"
click node_repositories "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/repositories.py"
click node_qualification_repo "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/qualification_repository.py"
click node_cognitive_repo "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/cognitive_repository.py"
click node_qualification_worker "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/worker/sira_worker/qualification.py"
click node_changefeed "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/changefeed/sira_changefeed/handler.py"
click node_aws_transport "https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/integrations/aws_services.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_workspace,node_webclient toneBlue
class node_api_routes,node_qualification_routes,node_seller_routes,node_exchange_routes,node_workflow,node_qualification,node_seller,node_exchange,node_aws_queues toneAmber
class node_cognitive,node_context,node_agent_runtime,node_bedrock_runtime,node_tool_broker,node_decision_graph,node_domain_evidence toneMint
class node_repositories,node_qualification_repo,node_cognitive_repo,node_cockroach toneRose
class node_qualification_worker,node_changefeed,node_aws_transport,node_users,node_bedrock toneIndigo
```

## Components

### User experience

- [SIRA and SEIL workspaces](https://github.com/sandip-pathe/sira-seil-cockroach-aws/tree/main/apps/web/app/(workspace)): `apps/web/app/(workspace)`
- [API client](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/packages/api-client/src/client.ts): `packages/api-client/src/client.ts`

### Application API

- [HTTP routes](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/routes.py): `services/api/sira_api/routes.py`
- [Qualification routes](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/qualification_routes.py): `services/api/sira_api/qualification_routes.py`
- [Seller routes](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/seller_routes.py): `services/api/sira_api/seller_routes.py`
- [Exchange routes](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/exchange_routes.py): `services/api/sira_api/exchange_routes.py`
- [Buyer workflow](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/service.py): `services/api/sira_api/service.py`
- [Product qualification](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/qualification_service.py): `services/api/sira_api/qualification_service.py`
- [Seller evidence workflow](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/seller_service.py): `services/api/sira_api/seller_service.py`
- [Bilateral exchange](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/exchange_service.py): `services/api/sira_api/exchange_service.py`

### Decision and agent runtime

- [Cognitive orchestration](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/api/sira_api/cognitive_engine.py): `services/api/sira_api/cognitive_engine.py`
- [Context assembly](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/context_assembler.py): `python/agents/sira_agents/context_assembler.py`
- [Cognitive runtime](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/cognitive_runtime.py): `python/agents/sira_agents/cognitive_runtime.py`
- [Bedrock runtime](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/bedrock_runtime.py): `python/agents/sira_agents/bedrock_runtime.py`
- [Tool authorization](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/agents/sira_agents/tool_broker.py): `python/agents/sira_agents/tool_broker.py`
- [Decision graph](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/decision_engine/graph_v1.py): `python/decision_engine/graph_v1.py`
- [Evidence pipeline](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/domain/evidence_pipeline.py): `python/domain/evidence_pipeline.py`

### Durable state

- [Workflow repositories](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/repositories.py): `python/persistence/repositories.py`
- [Qualification repository](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/qualification_repository.py): `python/persistence/qualification_repository.py`
- [Cognitive repository](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/persistence/cognitive_repository.py): `python/persistence/cognitive_repository.py`
- **CockroachDB**

### Background processing

- [Qualification worker](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/worker/sira_worker/qualification.py): `services/worker/sira_worker/qualification.py`
- [Changefeed handler](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/services/changefeed/sira_changefeed/handler.py): `services/changefeed/sira_changefeed/handler.py`
- [AWS transports](https://github.com/sandip-pathe/sira-seil-cockroach-aws/blob/main/python/integrations/aws_services.py): `python/integrations/aws_services.py`

### Other components

- **Buyer and seller**
- **Amazon Bedrock**
- **AWS queues and storage**

## Connections

- Buyer and seller → SIRA and SEIL workspaces: use (evidence: `README.md`)
- SIRA and SEIL workspaces → API client: send requests (evidence: `README.md`)
- API client → HTTP routes: call API (evidence: `README.md`)
- HTTP routes → Buyer workflow: delegate to (evidence: `services/api/sira_api/routes.py`)
- Qualification routes → Product qualification: delegate to (evidence: `services/api/sira_api/qualification_routes.py`)
- Seller routes → Seller evidence workflow: delegate to (evidence: `services/api/sira_api/seller_routes.py`)
- Exchange routes → Bilateral exchange: serve exchange
- Buyer workflow → Cognitive orchestration: orchestrate reasoning
- Cognitive orchestration → Context assembly: assemble context (evidence: `services/api/sira_api/cognitive_engine.py`)
- Cognitive orchestration → Cognitive runtime: request decision (evidence: `services/api/sira_api/cognitive_engine.py`)
- Cognitive runtime → Bedrock runtime: delegate reasoning (evidence: `python/agents/sira_agents/cognitive_runtime.py`)
- Bedrock runtime → Amazon Bedrock: invoke model (evidence: `README.md`)
- Cognitive orchestration → Tool authorization: validate tools (evidence: `services/api/sira_api/cognitive_engine.py`)
- Product qualification → Decision graph: evaluate fit
- Product qualification → Evidence pipeline: process evidence
- Buyer workflow → Workflow repositories: persist workflow
- Product qualification → Qualification repository: persist decisions
- Cognitive orchestration → Cognitive repository: record run (evidence: `services/api/sira_api/cognitive_engine.py`)
- Workflow repositories → CockroachDB: read and write (evidence: `README.md`)
- Qualification repository → CockroachDB: commit decisions (evidence: `README.md`)
- Cognitive repository → CockroachDB: commit runs (evidence: `README.md`)
- Qualification worker → Qualification repository: lease and persist (evidence: `services/worker/sira_worker/qualification.py`)
- Changefeed handler → AWS transports: publish changes
- AWS transports → AWS queues and storage: send or store (evidence: `python/integrations/aws_services.py`)
