# roopesh1815-bot/cipher architecture

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

- Interactive diagram: https://gitdiagram.com/roopesh1815-bot/cipher
- Repository: https://github.com/roopesh1815-bot/cipher

## Overview

CIPHER is an offline-first investigative network-analysis application. Its main workflow takes FIR, call-detail, financial, and social records through extraction, entity resolution and source fusion, then builds a contextual relationship graph and derives analytical outputs for investigator review. The FastAPI application exposes case-scoped and global views, with authentication, membership checks, document-vault operations, and audit logging. The README documents an isolated synthetic temporal-ML demonstration; it is separate from production graph analysis. Some subsystem links below reflect README-documented capabilities because their implementation files were not sampled.

Main entry points: [`pipeline/run_pipeline.py`](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/run_pipeline.py) (Pipeline runner), [`api/routers`](https://github.com/roopesh1815-bot/cipher/tree/main/api/routers) (Analysis and case APIs), [`api/main.py`](https://github.com/roopesh1815-bot/cipher/blob/main/api/main.py) (FastAPI application), [`core/auth.py`](https://github.com/roopesh1815-bot/cipher/blob/main/core/auth.py) (User authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Production analysis"]
  node_pipeline["Pipeline runner<br/>[run_pipeline.py]"]
  node_ingest["CSV ingestion<br/>[csv_importer.py]"]
  node_extract["Source extraction"]
  node_resolve["Entity resolution<br/>[entity_resolver.py]"]
  node_fusion["Source fusion<br/>[fusion_tagger.py]"]
  node_graph["Relationship graph<br/>[builder.py]"]
  node_centrality["Influencer metrics<br/>[centrality.py]"]
  node_community["Community detection<br/>[community.py]"]
  node_anomaly["Anomaly flags<br/>[anomaly.py]"]
  node_intelligence["Risk and links"]
  node_temporal["Temporal trends<br/>[temporal_engine.py]"]
  node_summaries["Case summaries<br/>[case_summariser.py]"]
  node_exports["Graph exports<br/>[exporter.py]"]
end

subgraph group_cases["Case operations"]
  node_case_manager["Case lifecycle<br/>[case_manager.py]"]
  node_vault["Protected document vault<br/>[case_vault.py]"]
  node_case_access["Case membership<br/>[case_access.py]"]
end

subgraph group_app["Application interface"]
  node_web["FastAPI application<br/>[main.py]"]
  node_routers["Analysis and case APIs"]
end

subgraph group_security["Identity and audit"]
  node_auth_routes["Login routes<br/>[auth.py]"]
  node_sessions["Session security<br/>[security.py]"]
  node_auth["User authentication<br/>[auth.py]"]
  node_audit["Hash-chained audit<br/>[audit.py]"]
  node_database[("SQLite records<br/>[db.py]")]
end

subgraph group_demo["Synthetic ML demo"]
  node_ml_demo["Synthetic temporal ML"]
end

node_investigator(("Investigator"))

node_investigator -->|"uses"| node_web
node_web -->|"registers"| node_routers
node_routers -->|"manage cases"| node_case_manager
node_routers -->|"serve vault"| node_vault
node_vault -->|"checks membership"| node_case_access
node_web -->|"authenticates requests"| node_sessions
node_auth_routes -->|"verifies credentials"| node_auth
node_auth_routes -->|"creates tokens"| node_sessions
node_sessions -->|"loads active user"| node_auth
node_auth -->|"reads users"| node_database
node_auth -->|"records actions"| node_audit
node_audit -->|"stores audit chain"| node_database
node_case_manager -->|"stores case records"| node_database
node_case_access -->|"checks memberships"| node_database
node_pipeline -->|"runs extraction"| node_extract
node_pipeline -->|"resolves entities"| node_resolve
node_pipeline -->|"tags sources"| node_fusion
node_pipeline -->|"builds graph"| node_graph
node_pipeline -->|"computes metrics"| node_centrality
node_pipeline -->|"detects communities"| node_community
node_pipeline -->|"detects anomalies"| node_anomaly
node_pipeline -->|"computes scores and links"| node_intelligence
node_pipeline -->|"runs temporal analysis"| node_temporal
node_pipeline -->|"summarizes cases"| node_summaries
node_pipeline -->|"exports graph"| node_exports
node_ingest -->|"creates cases"| node_case_manager
node_routers -.->|"serves influencer view"| node_centrality
node_routers -.->|"serves communities"| node_community
node_routers -.->|"serves alerts"| node_anomaly
node_routers -.->|"serves risk and links"| node_intelligence
node_routers -.->|"serves temporal alerts"| node_temporal
node_web -.->|"exposes separate demo"| node_ml_demo

click node_pipeline "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/run_pipeline.py"
click node_ingest "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/ingestion/csv_importer.py"
click node_extract "https://github.com/roopesh1815-bot/cipher/tree/main/pipeline/extraction"
click node_resolve "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/extraction/entity_resolver.py"
click node_fusion "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/extraction/fusion_tagger.py"
click node_graph "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/builder.py"
click node_centrality "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/centrality.py"
click node_community "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/community.py"
click node_anomaly "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/anomaly.py"
click node_intelligence "https://github.com/roopesh1815-bot/cipher/tree/main/pipeline/intelligence"
click node_temporal "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/intelligence/temporal_engine.py"
click node_summaries "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/intelligence/case_summariser.py"
click node_exports "https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/exporter.py"
click node_case_manager "https://github.com/roopesh1815-bot/cipher/blob/main/core/case_manager.py"
click node_vault "https://github.com/roopesh1815-bot/cipher/blob/main/api/routers/case_vault.py"
click node_case_access "https://github.com/roopesh1815-bot/cipher/blob/main/core/case_access.py"
click node_web "https://github.com/roopesh1815-bot/cipher/blob/main/api/main.py"
click node_routers "https://github.com/roopesh1815-bot/cipher/tree/main/api/routers"
click node_auth_routes "https://github.com/roopesh1815-bot/cipher/blob/main/api/routers/auth.py"
click node_sessions "https://github.com/roopesh1815-bot/cipher/blob/main/api/security.py"
click node_auth "https://github.com/roopesh1815-bot/cipher/blob/main/core/auth.py"
click node_audit "https://github.com/roopesh1815-bot/cipher/blob/main/core/audit.py"
click node_database "https://github.com/roopesh1815-bot/cipher/blob/main/core/db.py"
click node_ml_demo "https://github.com/roopesh1815-bot/cipher/blob/main/ml_experiment/temporal_link_demo.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_pipeline,node_ingest,node_extract,node_resolve,node_fusion,node_graph,node_centrality,node_community,node_anomaly,node_intelligence,node_temporal,node_summaries,node_exports toneBlue
class node_case_manager,node_vault,node_case_access toneAmber
class node_web,node_routers toneMint
class node_auth_routes,node_sessions,node_auth,node_audit,node_database toneRose
class node_ml_demo,node_investigator toneIndigo
```

## Components

### Production analysis

- [Pipeline runner](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/run_pipeline.py): `pipeline/run_pipeline.py`
- [CSV ingestion](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/ingestion/csv_importer.py): `pipeline/ingestion/csv_importer.py`
- [Source extraction](https://github.com/roopesh1815-bot/cipher/tree/main/pipeline/extraction): `pipeline/extraction`
- [Entity resolution](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/extraction/entity_resolver.py): `pipeline/extraction/entity_resolver.py`
- [Source fusion](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/extraction/fusion_tagger.py): `pipeline/extraction/fusion_tagger.py`
- [Relationship graph](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/builder.py): `pipeline/graph/builder.py`
- [Influencer metrics](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/centrality.py): `pipeline/graph/centrality.py`
- [Community detection](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/community.py): `pipeline/graph/community.py`
- [Anomaly flags](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/anomaly.py): `pipeline/graph/anomaly.py`
- [Risk and links](https://github.com/roopesh1815-bot/cipher/tree/main/pipeline/intelligence): `pipeline/intelligence`
- [Temporal trends](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/intelligence/temporal_engine.py): `pipeline/intelligence/temporal_engine.py`
- [Case summaries](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/intelligence/case_summariser.py): `pipeline/intelligence/case_summariser.py`
- [Graph exports](https://github.com/roopesh1815-bot/cipher/blob/main/pipeline/graph/exporter.py): `pipeline/graph/exporter.py`

### Case operations

- [Case lifecycle](https://github.com/roopesh1815-bot/cipher/blob/main/core/case_manager.py): `core/case_manager.py`
- [Protected document vault](https://github.com/roopesh1815-bot/cipher/blob/main/api/routers/case_vault.py): `api/routers/case_vault.py`
- [Case membership](https://github.com/roopesh1815-bot/cipher/blob/main/core/case_access.py): `core/case_access.py`

### Application interface

- [FastAPI application](https://github.com/roopesh1815-bot/cipher/blob/main/api/main.py): `api/main.py`
- [Analysis and case APIs](https://github.com/roopesh1815-bot/cipher/tree/main/api/routers): `api/routers`

### Identity and audit

- [Login routes](https://github.com/roopesh1815-bot/cipher/blob/main/api/routers/auth.py): `api/routers/auth.py`
- [Session security](https://github.com/roopesh1815-bot/cipher/blob/main/api/security.py): `api/security.py`
- [User authentication](https://github.com/roopesh1815-bot/cipher/blob/main/core/auth.py): `core/auth.py`
- [Hash-chained audit](https://github.com/roopesh1815-bot/cipher/blob/main/core/audit.py): `core/audit.py`
- [SQLite records](https://github.com/roopesh1815-bot/cipher/blob/main/core/db.py): `core/db.py`

### Synthetic ML demo

- [Synthetic temporal ML](https://github.com/roopesh1815-bot/cipher/blob/main/ml_experiment/temporal_link_demo.py): `ml_experiment/temporal_link_demo.py`

### Other components

- **Investigator**

## Connections

- Investigator → FastAPI application: uses
- FastAPI application → Analysis and case APIs: registers (evidence: `api/main.py`)
- Analysis and case APIs → Case lifecycle: manage cases (evidence: `api/routers/cases.py`)
- Analysis and case APIs → Protected document vault: serve vault (evidence: `api/main.py`)
- Protected document vault → Case membership: checks membership (evidence: `api/routers/case_vault.py`)
- FastAPI application → Session security: authenticates requests (evidence: `api/main.py`)
- Login routes → User authentication: verifies credentials (evidence: `api/routers/auth.py`)
- Login routes → Session security: creates tokens (evidence: `api/routers/auth.py`)
- Session security → User authentication: loads active user (evidence: `api/security.py`)
- User authentication → SQLite records: reads users (evidence: `core/auth.py`)
- User authentication → Hash-chained audit: records actions (evidence: `core/auth.py`)
- Hash-chained audit → SQLite records: stores audit chain (evidence: `core/audit.py`)
- Case lifecycle → SQLite records: stores case records (evidence: `core/case_manager.py`)
- Case membership → SQLite records: checks memberships (evidence: `core/case_access.py`)
- Pipeline runner → Source extraction: runs extraction (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Entity resolution: resolves entities (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Source fusion: tags sources (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Relationship graph: builds graph (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Influencer metrics: computes metrics (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Community detection: detects communities (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Anomaly flags: detects anomalies (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Risk and links: computes scores and links (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Temporal trends: runs temporal analysis (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Case summaries: summarizes cases (evidence: `pipeline/run_pipeline.py`)
- Pipeline runner → Graph exports: exports graph (evidence: `pipeline/run_pipeline.py`)
- CSV ingestion → Case lifecycle: creates cases (evidence: `pipeline/ingestion/csv_importer.py`)
- Analysis and case APIs → Influencer metrics: serves influencer view
- Analysis and case APIs → Community detection: serves communities
- Analysis and case APIs → Anomaly flags: serves alerts
- Analysis and case APIs → Risk and links: serves risk and links
- Analysis and case APIs → Temporal trends: serves temporal alerts
- FastAPI application → Synthetic temporal ML: exposes separate demo
