# vikhayatrana0110-crypto/bastion--a-secure-ai-assistant architecture

> Architecture diagram of the GitHub repository vikhayatrana0110-crypto/bastion--a-secure-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant
- Repository: https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant

## Overview

Bastion is an early-stage secure internal knowledge assistant. Its current runtime provides database security checks, authentication primitives, and document-ingestion utilities; it does not yet expose the documented ask-to-cited-answer workflow. The graph separates implemented components from planned retrieval and guardrail capabilities. Source excerpts show startup checks, database access, authentication, and markdown chunking; other documented connections are marked as planned or omitted where implementation evidence is unavailable.

Main entry points: [`src/bastion/db/pool.py`](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/pool.py) (Connection Pool), [`src/bastion/auth/login.py`](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/login.py) (Authentication), [`src/bastion/main.py`](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/main.py) (FastAPI App), [`src/bastion/auth/tokens.py`](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/tokens.py) (JWT Tokens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application Runtime"]
  node_app["FastAPI App<br/>[main.py]"]
  node_settings["Settings<br/>[config.py]"]
end

subgraph group_security["Identity and Access"]
  node_login["Authentication<br/>[login.py]"]
  node_passwords["Password Hashing<br/>[passwords.py]"]
  node_tokens["JWT Tokens<br/>[tokens.py]"]
  node_access["Access Context<br/>[access.py]"]
end

subgraph group_storage["Database Security"]
  node_pool["Connection Pool<br/>[pool.py]"]
  node_postgres[("Postgres")]
  node_selfcheck["Security Checks<br/>[selfcheck.py]"]
  node_schema["RLS Schema"]
end

subgraph group_ingestion["Document Ingestion"]
  node_validation["Document Validation<br/>[validate.py]"]
  node_markdown["Markdown Parser<br/>[markdown.py]"]
  node_tokenizer["Token Counting<br/>[tokenizer.py]"]
  node_chunking["Chunking<br/>[chunking.py]"]
end

node_employee(("Employee"))
node_retrieval["Hybrid Retrieval &#40;planned&#41;"]
node_guardrails["Answer Guardrails &#40;planned&#41;"]
node_answer["Cited Answer &#40;planned&#41;"]
node_evaluation["Leak Evaluation &#40;planned&#41;"]

node_app -->|"opens connection"| node_pool
node_app -->|"checks invariants"| node_selfcheck
node_pool -->|"loads connection URL"| node_settings
node_login -->|"verifies passwords"| node_passwords
node_login -->|"reads tokens"| node_tokens
node_login -->|"queries identity"| node_pool
node_tokens -->|"loads signing secret"| node_settings
node_access -->|"opens access transaction"| node_pool
node_selfcheck -->|"checks privileges"| node_postgres
node_schema -->|"defines policies"| node_postgres
node_chunking -->|"chunks parsed blocks"| node_markdown
node_employee -.->|"asks about documents"| node_retrieval
node_retrieval -.->|"returns cited answers"| node_answer
node_guardrails -.->|"checks grounding"| node_answer
node_evaluation -.->|"tests access leaks"| node_schema

click node_app "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/main.py"
click node_settings "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/config.py"
click node_login "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/login.py"
click node_passwords "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/passwords.py"
click node_tokens "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/tokens.py"
click node_access "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/access.py"
click node_pool "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/pool.py"
click node_postgres "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/tree/main/migrations"
click node_selfcheck "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/selfcheck.py"
click node_schema "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/tree/main/migrations"
click node_validation "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/validate.py"
click node_markdown "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/markdown.py"
click node_tokenizer "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/tokenizer.py"
click node_chunking "https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/chunking.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_app,node_settings toneBlue
class node_login,node_passwords,node_tokens,node_access toneAmber
class node_pool,node_postgres,node_selfcheck,node_schema toneMint
class node_validation,node_markdown,node_tokenizer,node_chunking toneRose
class node_employee,node_retrieval,node_guardrails,node_answer,node_evaluation toneIndigo
```

## Components

### Application Runtime

- [FastAPI App](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/main.py): `src/bastion/main.py`
- [Settings](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/config.py): `src/bastion/config.py`

### Identity and Access

- [Authentication](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/login.py): `src/bastion/auth/login.py`
- [Password Hashing](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/passwords.py): `src/bastion/auth/passwords.py`
- [JWT Tokens](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/auth/tokens.py): `src/bastion/auth/tokens.py`
- [Access Context](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/access.py): `src/bastion/db/access.py`

### Database Security

- [Connection Pool](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/pool.py): `src/bastion/db/pool.py`
- [Postgres](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/tree/main/migrations): `migrations`
- [Security Checks](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/db/selfcheck.py): `src/bastion/db/selfcheck.py`
- [RLS Schema](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/tree/main/migrations): `migrations`

### Document Ingestion

- [Document Validation](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/validate.py): `src/bastion/ingestion/validate.py`
- [Markdown Parser](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/markdown.py): `src/bastion/ingestion/markdown.py`
- [Token Counting](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/tokenizer.py): `src/bastion/ingestion/tokenizer.py`
- [Chunking](https://github.com/vikhayatrana0110-crypto/bastion--a-secure-ai-assistant/blob/main/src/bastion/ingestion/chunking.py): `src/bastion/ingestion/chunking.py`

### Other components

- **Employee**
- **Hybrid Retrieval (planned)**
- **Answer Guardrails (planned)**
- **Cited Answer (planned)**
- **Leak Evaluation (planned)**

## Connections

- FastAPI App → Connection Pool: opens connection (evidence: `src/bastion/main.py`)
- FastAPI App → Security Checks: checks invariants (evidence: `src/bastion/main.py`)
- Connection Pool → Settings: loads connection URL (evidence: `src/bastion/db/pool.py`)
- Authentication → Password Hashing: verifies passwords (evidence: `src/bastion/auth/login.py`)
- Authentication → JWT Tokens: reads tokens (evidence: `src/bastion/auth/login.py`)
- Authentication → Connection Pool: queries identity (evidence: `src/bastion/auth/login.py`)
- JWT Tokens → Settings: loads signing secret (evidence: `src/bastion/auth/tokens.py`)
- Access Context → Connection Pool: opens access transaction (evidence: `src/bastion/db/access.py`)
- Security Checks → Postgres: checks privileges (evidence: `src/bastion/db/selfcheck.py`)
- RLS Schema → Postgres: defines policies (evidence: `README.md`)
- Chunking → Markdown Parser: chunks parsed blocks (evidence: `src/bastion/ingestion/chunking.py`)
- Employee → Hybrid Retrieval (planned): asks about documents (evidence: `README.md`)
- Hybrid Retrieval (planned) → Cited Answer (planned): returns cited answers (evidence: `README.md`)
- Answer Guardrails (planned) → Cited Answer (planned): checks grounding (evidence: `README.md`)
- Leak Evaluation (planned) → RLS Schema: tests access leaks (evidence: `README.md`)
