# niethesan96/gitops-human architecture

> Architecture diagram of the GitHub repository niethesan96/gitops-human, 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/niethesan96/gitops-human
- Repository: https://github.com/niethesan96/gitops-human

## Overview

GitOps for Humans turns categorized Git commit messages into productivity records and spreadsheet updates, with brainstorm commits also producing a roadmap. The documented workflow runs from a Git push through GitHub and an ngrok tunnel to the Flask webhook, which parses messages with Gemini and dispatches them to PostgreSQL and Google Sheets. README describes a PostgreSQL trigger, but its implementation is not present in the supplied source; the graph shows it only as a documented capability. Runtime behavior is concentrated in app.py.

Main entry points: [`app.py`](https://github.com/niethesan96/gitops-human/blob/main/app.py) (Type dispatcher), [`ngrok.exe`](https://github.com/niethesan96/gitops-human/blob/main/ngrok.exe) (ngrok tunnel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Commit Ingress"]
  node_git["Git push"]
  node_github["GitHub webhook"]
  node_tunnel["ngrok tunnel<br/>[ngrok.exe]"]
  node_webhook["Webhook handler<br/>[app.py]"]
end

subgraph group_processing["AI Processing"]
  node_commit_parser["Commit parser<br/>[app.py]"]
  node_dispatcher["Type dispatcher<br/>[app.py]"]
  node_roadmap["Roadmap generator<br/>[app.py]"]
end

subgraph group_records["Record Routing"]
  node_commit_store[("Commit records")]
  node_db_trigger["Commit trigger"]
  node_db_connection["DB connection<br/>[app.py]"]
  node_tasks_bugs[("Tasks and bugs<br/>[app.py]")]
  node_meetings[("Meetings<br/>[app.py]")]
  node_expenses[("Expenses<br/>[app.py]")]
  node_ideas[("Ideas and brainstorms<br/>[app.py]")]
  node_sheets_writer["Sheets tab writer<br/>[app.py]"]
end

subgraph group_integrations["External Services"]
  node_gemini["Google Gemini"]
  node_sheets[("Google Sheets")]
end

node_developer(("Developer"))

node_developer -->|"pushes commits"| node_git
node_git -->|"sends push"| node_github
node_github -->|"posts webhook"| node_tunnel
node_tunnel -->|"forwards payload"| node_webhook
node_webhook -->|"opens connection"| node_db_connection
node_webhook -->|"inserts raw commits"| node_commit_store
node_commit_store -.->|"fires trigger"| node_db_trigger
node_webhook -->|"parses message"| node_commit_parser
node_commit_parser -->|"requests JSON parse"| node_gemini
node_webhook -->|"routes parsed commit"| node_dispatcher
node_dispatcher -->|"generates brainstorm roadmap"| node_roadmap
node_roadmap -->|"requests roadmap JSON"| node_gemini
node_dispatcher -->|"writes task or bug"| node_tasks_bugs
node_dispatcher -->|"writes meeting"| node_meetings
node_dispatcher -->|"writes expense"| node_expenses
node_dispatcher -->|"writes idea or topic"| node_ideas
node_dispatcher -->|"appends categorized row"| node_sheets_writer
node_sheets_writer -->|"creates tabs and appends rows"| node_sheets
node_webhook -->|"marks processed"| node_commit_store

click node_tunnel "https://github.com/niethesan96/gitops-human/blob/main/ngrok.exe"
click node_webhook "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_db_connection "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_commit_parser "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_dispatcher "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_roadmap "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_tasks_bugs "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_meetings "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_expenses "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_ideas "https://github.com/niethesan96/gitops-human/blob/main/app.py"
click node_sheets_writer "https://github.com/niethesan96/gitops-human/blob/main/app.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_git,node_github,node_tunnel,node_webhook toneBlue
class node_commit_parser,node_dispatcher,node_roadmap toneAmber
class node_commit_store,node_db_trigger,node_db_connection,node_tasks_bugs,node_meetings,node_expenses,node_ideas,node_sheets_writer toneMint
class node_gemini,node_sheets toneRose
class node_developer toneIndigo
```

## Components

### Commit Ingress

- **Git push**
- **GitHub webhook**
- [ngrok tunnel](https://github.com/niethesan96/gitops-human/blob/main/ngrok.exe): `ngrok.exe`
- [Webhook handler](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`

### AI Processing

- [Commit parser](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Type dispatcher](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Roadmap generator](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`

### Record Routing

- **Commit records**
- **Commit trigger**
- [DB connection](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Tasks and bugs](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Meetings](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Expenses](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Ideas and brainstorms](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`
- [Sheets tab writer](https://github.com/niethesan96/gitops-human/blob/main/app.py): `app.py`

### External Services

- **Google Gemini**
- **Google Sheets**

### Other components

- **Developer**

## Connections

- Developer → Git push: pushes commits
- Git push → GitHub webhook: sends push
- GitHub webhook → ngrok tunnel: posts webhook
- ngrok tunnel → Webhook handler: forwards payload
- Webhook handler → DB connection: opens connection
- Webhook handler → Commit records: inserts raw commits
- Commit records → Commit trigger: fires trigger
- Webhook handler → Commit parser: parses message
- Commit parser → Google Gemini: requests JSON parse
- Webhook handler → Type dispatcher: routes parsed commit
- Type dispatcher → Roadmap generator: generates brainstorm roadmap
- Roadmap generator → Google Gemini: requests roadmap JSON
- Type dispatcher → Tasks and bugs: writes task or bug
- Type dispatcher → Meetings: writes meeting
- Type dispatcher → Expenses: writes expense
- Type dispatcher → Ideas and brainstorms: writes idea or topic
- Type dispatcher → Sheets tab writer: appends categorized row
- Sheets tab writer → Google Sheets: creates tabs and appends rows
- Webhook handler → Commit records: marks processed