# rohithpranov07/helix architecture

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

- Interactive diagram: https://gitdiagram.com/rohithpranov07/helix
- Repository: https://github.com/rohithpranov07/helix

## Overview

HELIX is an autonomous maintenance layer for AI-built software: users connect a repository, then inspect its intent/code alignment, security findings, entropy, incidents, and repair activity in a web control plane. Its engine organs capture and pair intent, scan and heal vulnerabilities, validate repairs in a Shadow twin, track recurring fixes, measure entropy, handle incidents, and gate work by homeostasis. MongoDB stores the system’s biological memory and records; Groq and Gemini provide cognition and perception. The README documents n8n reflex arcs, but their runtime wiring is not present in the supplied tree.

Main entry points: [`packages/db/src`](https://github.com/rohithpranov07/helix/tree/main/packages/db/src) (MongoDB), [`packages/engine/src/immune`](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/immune) (Immune System), [`packages/engine/src/genome`](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/genome) (Intent Genome), [`apps/web/app/api`](https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api) (API Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_dashboard["Dashboard"]
  node_api["API Routes"]
  node_vitals["Vital Signs<br/>[route.ts]"]
  node_stream["Activity Stream<br/>[route.ts]"]
  node_github_oauth["GitHub Connect"]
end

subgraph group_genome["Genome"]
  node_genome_api["Genome Routes"]
  node_genome["Intent Genome"]
end

subgraph group_repair["Repair Organs"]
  node_immune_api["Immune Routes"]
  node_immune["Immune System"]
  node_memory["Immune Memory"]
  node_shadow["Shadow Verification"]
end

subgraph group_operations["Operations"]
  node_metabolism_api["Metabolism Routes<br/>[route.ts]"]
  node_metabolism["Metabolism"]
  node_nervous["Nervous System"]
  node_governor["Governor"]
end

subgraph group_platform["Shared Platform"]
  node_ai["AI Clients"]
  node_db[("MongoDB")]
end

node_user(("Engineer"))
node_github(("GitHub"))
node_target["ShopLite Target"]
node_shadow_twin["Shadow Twin"]
node_n8n["n8n Workflows"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests"| node_api
node_api -->|"dispatches"| node_genome_api
node_api -->|"dispatches"| node_immune_api
node_api -->|"dispatches"| node_metabolism_api
node_genome_api -->|"calls"| node_genome
node_immune_api -->|"calls"| node_immune
node_metabolism_api -->|"calls"| node_metabolism
node_github_oauth -->|"authorizes"| node_github
node_github_oauth -->|"uses integration"| node_genome
node_github_oauth -->|"saves connection"| node_db
node_genome -->|"reads repository"| node_github
node_genome -->|"stores strands"| node_db
node_immune -->|"scans and patches"| node_target
node_immune -->|"requests verification"| node_shadow
node_shadow -->|"tests changes"| node_shadow_twin
node_shadow -->|"stores proofs"| node_db
node_immune -->|"stores findings"| node_db
node_immune -->|"mints antibodies"| node_memory
node_memory -->|"stores antibodies"| node_db
node_metabolism -->|"stores measurements"| node_db
node_nervous -->|"stores incidents"| node_db
node_governor -->|"stores homeostasis"| node_db
node_genome -->|"requests pairing"| node_ai
node_metabolism -->|"requests analysis"| node_ai
node_immune -->|"requests reasoning"| node_ai
node_nervous -->|"requests reasoning"| node_ai
node_vitals -->|"reads organ records"| node_db
node_vitals -.->|"fetches deploy data"| node_nervous
node_stream -->|"polls activity records"| node_db
node_n8n -.->|"triggers reflex arcs"| node_immune_api
node_n8n -.->|"triggers scheduled runs"| node_metabolism_api
node_n8n -.->|"triggers reflex arcs"| node_nervous
node_n8n -.->|"triggers checks"| node_governor

click node_dashboard "https://github.com/rohithpranov07/helix/tree/main/apps/web/app/dashboard"
click node_api "https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api"
click node_vitals "https://github.com/rohithpranov07/helix/blob/main/apps/web/app/api/vitals/route.ts"
click node_stream "https://github.com/rohithpranov07/helix/blob/main/apps/web/app/api/stream/route.ts"
click node_github_oauth "https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api/auth/github"
click node_genome_api "https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api/reflex"
click node_genome "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/genome"
click node_target "https://github.com/rohithpranov07/helix/tree/main/apps/target"
click node_immune_api "https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api/reflex"
click node_immune "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/immune"
click node_memory "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/memory"
click node_shadow "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/shadow"
click node_metabolism_api "https://github.com/rohithpranov07/helix/blob/main/apps/web/app/api/metabolism-scan/route.ts"
click node_metabolism "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/metabolism"
click node_nervous "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/nervous"
click node_governor "https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/governor"
click node_ai "https://github.com/rohithpranov07/helix/tree/main/packages/ai/src"
click node_db "https://github.com/rohithpranov07/helix/tree/main/packages/db/src"

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_dashboard,node_api,node_vitals,node_stream,node_github_oauth toneBlue
class node_genome_api,node_genome toneAmber
class node_immune_api,node_immune,node_memory,node_shadow toneMint
class node_metabolism_api,node_metabolism,node_nervous,node_governor toneRose
class node_ai,node_db,node_user,node_github,node_shadow_twin,node_n8n toneIndigo
class node_target toneTeal
```

## Components

### Control Plane

- [Dashboard](https://github.com/rohithpranov07/helix/tree/main/apps/web/app/dashboard): `apps/web/app/dashboard`
- [API Routes](https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api): `apps/web/app/api`
- [Vital Signs](https://github.com/rohithpranov07/helix/blob/main/apps/web/app/api/vitals/route.ts): `apps/web/app/api/vitals/route.ts`
- [Activity Stream](https://github.com/rohithpranov07/helix/blob/main/apps/web/app/api/stream/route.ts): `apps/web/app/api/stream/route.ts`
- [GitHub Connect](https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api/auth/github): `apps/web/app/api/auth/github`

### Genome

- [Genome Routes](https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api/reflex): `apps/web/app/api/reflex`
- [Intent Genome](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/genome): `packages/engine/src/genome`

### Repair Organs

- [Immune Routes](https://github.com/rohithpranov07/helix/tree/main/apps/web/app/api/reflex): `apps/web/app/api/reflex`
- [Immune System](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/immune): `packages/engine/src/immune`
- [Immune Memory](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/memory): `packages/engine/src/memory`
- [Shadow Verification](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/shadow): `packages/engine/src/shadow`

### Operations

- [Metabolism Routes](https://github.com/rohithpranov07/helix/blob/main/apps/web/app/api/metabolism-scan/route.ts): `apps/web/app/api/metabolism-scan/route.ts`
- [Metabolism](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/metabolism): `packages/engine/src/metabolism`
- [Nervous System](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/nervous): `packages/engine/src/nervous`
- [Governor](https://github.com/rohithpranov07/helix/tree/main/packages/engine/src/governor): `packages/engine/src/governor`

### Shared Platform

- [AI Clients](https://github.com/rohithpranov07/helix/tree/main/packages/ai/src): `packages/ai/src`
- [MongoDB](https://github.com/rohithpranov07/helix/tree/main/packages/db/src): `packages/db/src`

### Other components

- **Engineer**
- **GitHub**
- [ShopLite Target](https://github.com/rohithpranov07/helix/tree/main/apps/target): `apps/target`
- **Shadow Twin**
- **n8n Workflows**

## Connections

- Engineer → Dashboard: uses
- Dashboard → API Routes: requests
- API Routes → Genome Routes: dispatches
- API Routes → Immune Routes: dispatches
- API Routes → Metabolism Routes: dispatches
- Genome Routes → Intent Genome: calls
- Immune Routes → Immune System: calls
- Metabolism Routes → Metabolism: calls
- GitHub Connect → GitHub: authorizes
- GitHub Connect → Intent Genome: uses integration
- GitHub Connect → MongoDB: saves connection
- Intent Genome → GitHub: reads repository
- Intent Genome → MongoDB: stores strands
- Immune System → ShopLite Target: scans and patches
- Immune System → Shadow Verification: requests verification
- Shadow Verification → Shadow Twin: tests changes
- Shadow Verification → MongoDB: stores proofs
- Immune System → MongoDB: stores findings
- Immune System → Immune Memory: mints antibodies
- Immune Memory → MongoDB: stores antibodies
- Metabolism → MongoDB: stores measurements
- Nervous System → MongoDB: stores incidents
- Governor → MongoDB: stores homeostasis
- Intent Genome → AI Clients: requests pairing
- Metabolism → AI Clients: requests analysis
- Immune System → AI Clients: requests reasoning
- Nervous System → AI Clients: requests reasoning
- Vital Signs → MongoDB: reads organ records
- Vital Signs → Nervous System: fetches deploy data
- Activity Stream → MongoDB: polls activity records
- n8n Workflows → Immune Routes: triggers reflex arcs
- n8n Workflows → Metabolism Routes: triggers scheduled runs
- n8n Workflows → Nervous System: triggers reflex arcs
- n8n Workflows → Governor: triggers checks