# sarthakroy-1/astrion architecture

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

- Interactive diagram: https://gitdiagram.com/sarthakroy-1/astrion
- Repository: https://github.com/sarthakroy-1/astrion

## Overview

ASTRION is a tenant-scoped logistics support and operations agent. A user asks a question; the agent investigates workspace records and authority-ranked documents, while deterministic policy code computes decisions. The response exposes evidence and uncertainty. Proposed state changes stop for explicit confirmation before execution. The graph preserves the documented identity/workspace, document, operations, audit, and durable-storage capabilities. Some subsystem links rely on README documentation or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`app/backend/services/records.py`](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/records.py) (Structured records), [`app/backend/db/__init__.py`](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/db/__init__.py) (PostgreSQL / SQLite), [`app/backend/agent/orchestrator.py`](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/agent/orchestrator.py) (Agent orchestrator), [`app/backend/tools/registry.py`](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/tools/registry.py) (Agent tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Next.js workspace UI<br/>[page.tsx]"]
  node_conversation["Conversation workflow<br/>[useConversation.ts]"]
end

subgraph group_access["Identity and tenancy"]
  node_api["FastAPI routes<br/>[routes.py]"]
  node_auth["Authentication flows<br/>[auth_routes.py]"]
  node_identity["OAuth and verification<br/>[identity_routes.py]"]
  node_workspace["Workspace membership"]
  node_tenancy["Tenant scope<br/>[tenancy.py]"]
end

subgraph group_investigation["Agent investigation"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_tools["Agent tool registry<br/>[registry.py]"]
  node_retrieval["Authority-ranked retrieval<br/>[search.py]"]
  node_records["Structured records<br/>[records.py]"]
  node_ingestion["Document ingestion"]
end

subgraph group_decisions["Decisions and actions"]
  node_policy["Deterministic policy engine<br/>[service_credit.py]"]
  node_actions["Confirmation-gated actions<br/>[actions.py]"]
  node_operations["Operations intelligence<br/>[service.py]"]
end

subgraph group_platform["Data and operations"]
  node_database[("PostgreSQL / SQLite<br/>[__init__.py]")]
  node_storage[("Document object storage<br/>[store.py]")]
  node_audit[("Hash-chained audit<br/>[audit.py]")]
end

node_user(("Support user"))
node_llm{{"LLM provider"}}

node_user -->|"asks or confirms"| node_frontend
node_frontend -->|"sends requests"| node_api
node_api -.->|"routes identity requests"| node_auth
node_api -->|"builds agent context"| node_orchestrator
node_auth -->|"stores credentials"| node_database
node_identity -->|"completes sign-in"| node_auth
node_workspace -->|"enforces workspace scope"| node_tenancy
node_workspace -->|"reads memberships"| node_database
node_orchestrator -->|"dispatches tools"| node_tools
node_orchestrator -.->|"uses planner provider"| node_llm
node_tools -.->|"retrieves evidence"| node_retrieval
node_tools -.->|"looks up records"| node_records
node_tools -.->|"evaluates rules"| node_policy
node_orchestrator -->|"prepares actions"| node_actions
node_orchestrator -->|"reads workspace data"| node_records
node_policy -->|"gathers policy evidence"| node_retrieval
node_policy -->|"reads order facts"| node_records
node_records -->|"scopes queries"| node_tenancy
node_ingestion -->|"indexes documents"| node_database
node_ingestion -.->|"stores originals"| node_storage
node_retrieval -.->|"searches indexed sources"| node_database
node_records -.->|"reads tenant records"| node_database
node_actions -.->|"persists action state"| node_database
node_operations -->|"analyzes records"| node_records
node_auth -->|"records security events"| node_audit
node_actions -.->|"records action events"| node_audit

click node_frontend "https://github.com/sarthakroy-1/astrion/blob/main/app/frontend/src/app/workspace/page.tsx"
click node_conversation "https://github.com/sarthakroy-1/astrion/blob/main/app/frontend/src/hooks/useConversation.ts"
click node_api "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/routes.py"
click node_auth "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/auth_routes.py"
click node_identity "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/identity_routes.py"
click node_workspace "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/workspace_routes.py"
click node_tenancy "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/tenancy.py"
click node_orchestrator "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/agent/orchestrator.py"
click node_tools "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/tools/registry.py"
click node_retrieval "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/retrieval/search.py"
click node_records "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/records.py"
click node_ingestion "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/document_ingestion.py"
click node_policy "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/policies/service_credit.py"
click node_actions "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/actions.py"
click node_operations "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/operations/service.py"
click node_database "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/db/__init__.py"
click node_storage "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/storage/store.py"
click node_audit "https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/audit.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_frontend,node_conversation,node_user toneBlue
class node_api,node_auth,node_identity,node_workspace,node_tenancy toneAmber
class node_orchestrator,node_tools,node_retrieval,node_records,node_ingestion toneMint
class node_policy,node_actions,node_operations toneRose
class node_database,node_storage,node_audit,node_llm toneIndigo
```

## Components

### User experience

- [Next.js workspace UI](https://github.com/sarthakroy-1/astrion/blob/main/app/frontend/src/app/workspace/page.tsx): `app/frontend/src/app/workspace/page.tsx`
- [Conversation workflow](https://github.com/sarthakroy-1/astrion/blob/main/app/frontend/src/hooks/useConversation.ts): `app/frontend/src/hooks/useConversation.ts`

### Identity and tenancy

- [FastAPI routes](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/routes.py): `app/backend/api/routes.py`
- [Authentication flows](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/auth_routes.py): `app/backend/api/auth_routes.py`
- [OAuth and verification](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/identity_routes.py): `app/backend/api/identity_routes.py`
- [Workspace membership](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/api/workspace_routes.py): `app/backend/api/workspace_routes.py`
- [Tenant scope](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/tenancy.py): `app/backend/tenancy.py`

### Agent investigation

- [Agent orchestrator](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/agent/orchestrator.py): `app/backend/agent/orchestrator.py`
- [Agent tool registry](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/tools/registry.py): `app/backend/tools/registry.py`
- [Authority-ranked retrieval](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/retrieval/search.py): `app/backend/retrieval/search.py`
- [Structured records](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/records.py): `app/backend/services/records.py`
- [Document ingestion](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/document_ingestion.py): `app/backend/services/document_ingestion.py`

### Decisions and actions

- [Deterministic policy engine](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/policies/service_credit.py): `app/backend/policies/service_credit.py`
- [Confirmation-gated actions](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/actions.py): `app/backend/services/actions.py`
- [Operations intelligence](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/operations/service.py): `app/backend/operations/service.py`

### Data and operations

- [PostgreSQL / SQLite](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/db/__init__.py): `app/backend/db/__init__.py`
- [Document object storage](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/storage/store.py): `app/backend/storage/store.py`
- [Hash-chained audit](https://github.com/sarthakroy-1/astrion/blob/main/app/backend/services/audit.py): `app/backend/services/audit.py`

### Other components

- **Support user**
- **LLM provider**

## Connections

- Support user → Next.js workspace UI: asks or confirms
- Next.js workspace UI → FastAPI routes: sends requests
- FastAPI routes → Authentication flows: routes identity requests
- FastAPI routes → Agent orchestrator: builds agent context
- Authentication flows → PostgreSQL / SQLite: stores credentials
- OAuth and verification → Authentication flows: completes sign-in (evidence: `app/backend/api/identity_routes.py`)
- Workspace membership → Tenant scope: enforces workspace scope (evidence: `app/backend/api/workspace_routes.py`)
- Workspace membership → PostgreSQL / SQLite: reads memberships (evidence: `app/backend/api/workspace_routes.py`)
- Agent orchestrator → Agent tool registry: dispatches tools (evidence: `app/backend/agent/orchestrator.py`)
- Agent orchestrator → LLM provider: uses planner provider
- Agent tool registry → Authority-ranked retrieval: retrieves evidence
- Agent tool registry → Structured records: looks up records
- Agent tool registry → Deterministic policy engine: evaluates rules
- Agent orchestrator → Confirmation-gated actions: prepares actions (evidence: `app/backend/agent/orchestrator.py`)
- Agent orchestrator → Structured records: reads workspace data (evidence: `app/backend/agent/orchestrator.py`)
- Deterministic policy engine → Authority-ranked retrieval: gathers policy evidence (evidence: `app/backend/policies/service_credit.py`)
- Deterministic policy engine → Structured records: reads order facts (evidence: `app/backend/policies/service_credit.py`)
- Structured records → Tenant scope: scopes queries (evidence: `app/backend/services/records.py`)
- Document ingestion → PostgreSQL / SQLite: indexes documents (evidence: `app/backend/services/document_ingestion.py`)
- Document ingestion → Document object storage: stores originals
- Authority-ranked retrieval → PostgreSQL / SQLite: searches indexed sources
- Structured records → PostgreSQL / SQLite: reads tenant records
- Confirmation-gated actions → PostgreSQL / SQLite: persists action state
- Operations intelligence → Structured records: analyzes records (evidence: `app/backend/operations/service.py`)
- Authentication flows → Hash-chained audit: records security events (evidence: `app/backend/api/auth_routes.py`)
- Confirmation-gated actions → Hash-chained audit: records action events