# gitbyjay25/hackvilla-uk04 architecture

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

- Interactive diagram: https://gitdiagram.com/gitbyjay25/hackvilla-uk04
- Repository: https://github.com/gitbyjay25/hackvilla-uk04

## Overview

Nexarch reconstructs production architecture from SDK-captured runtime spans, analyzes the resulting dependency graph, and presents issues and alternative workflows for comparison. The primary path runs from application instrumentation through telemetry ingestion and analysis to dashboard or MCP access. The README documents SDK observation, graph reconstruction, issue detection, workflow alternatives, and comparative analysis; sampled code confirms ingestion, streaming, reasoning, and MCP entry points. Several service and dashboard implementations are unsampled, so their internal wiring is not inferred here.

Main entry points: [`Server/streaming/pipeline.py`](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/pipeline.py) (Streaming pipeline), [`Server/main.py`](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/main.py) (FastAPI application), [`Server/api/ingest.py`](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/api/ingest.py) (Telemetry ingestion), [`Server/reasoning/langgraph_pipeline.py`](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/langgraph_pipeline.py) (Workflow reasoning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observation["Runtime observation"]
  node_sdk["SDK tracing<br/>[span.py]"]
  node_instrumentation["Library hooks"]
  node_exporter["HTTP exporter<br/>[http.py]"]
end

subgraph group_platform["Ingestion and streaming"]
  node_api["FastAPI application<br/>[main.py]"]
  node_ingest["Telemetry ingestion<br/>[ingest.py]"]
  node_ingest_service["Span persistence<br/>[ingest_service.py]"]
  node_database[("Platform database<br/>[models.py]")]
  node_stream["Streaming pipeline<br/>[pipeline.py]"]
  node_transforms["Graph transforms<br/>[graph_builder.py]"]
  node_websocket["Live updates<br/>[websocket.py]"]
end

subgraph group_intelligence["Architecture intelligence"]
  node_reasoning["Workflow reasoning"]
  node_rules["Issue rules<br/>[rules.py]"]
  node_graph_analysis["Graph analysis<br/>[graph_analysis.py]"]
  node_workflow_service["Workflow generation"]
  node_analytics["Project analytics"]
end

subgraph group_interfaces["Product interfaces"]
  node_dashboard["Web dashboard<br/>[page.js]"]
  node_api_client["Frontend API client<br/>[api-client.js]"]
end

subgraph group_access["External access"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_tools["Architecture tools<br/>[tools.py]"]
end

node_app(("Instrumented application"))
node_user(("Team member"))

node_app -->|"runs with"| node_instrumentation
node_instrumentation -->|"captures spans"| node_sdk
node_sdk -->|"exports telemetry"| node_exporter
node_exporter -->|"posts spans"| node_ingest
node_api -->|"registers routes"| node_ingest
node_ingest -->|"stores spans"| node_ingest_service
node_ingest_service -->|"writes spans"| node_database
node_api -->|"starts pipeline"| node_stream
node_stream -->|"builds graph tables"| node_transforms
node_stream -->|"pushes updates"| node_websocket
node_reasoning -->|"detects issues"| node_rules
node_reasoning -->|"analyzes graph"| node_graph_analysis
node_user -->|"views insights"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_api_client -->|"calls endpoints"| node_api
node_mcp_server -->|"dispatches tools"| node_mcp_tools

click node_sdk "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/nexarch-sdk/nexarch/tracing/span.py"
click node_instrumentation "https://github.com/gitbyjay25/hackvilla-uk04/tree/main/nexarch-sdk/nexarch/instrumentation"
click node_exporter "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/nexarch-sdk/nexarch/exporters/http.py"
click node_api "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/main.py"
click node_ingest "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/api/ingest.py"
click node_ingest_service "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/services/ingest_service.py"
click node_database "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/db/models.py"
click node_stream "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/pipeline.py"
click node_transforms "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/transforms/graph_builder.py"
click node_websocket "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/websocket.py"
click node_reasoning "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/langgraph_pipeline.py"
click node_rules "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/rules.py"
click node_graph_analysis "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/graph_analysis.py"
click node_workflow_service "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/services/workflow_generator.py"
click node_analytics "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/services/project_analytics_service.py"
click node_dashboard "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/frontend/src/app/dashboard/page.js"
click node_api_client "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/frontend/src/lib/api-client.js"
click node_mcp_server "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/mcp_server/server.py"
click node_mcp_tools "https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/mcp_server/tools.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_sdk,node_instrumentation,node_exporter toneBlue
class node_api,node_ingest,node_ingest_service,node_database,node_stream,node_transforms,node_websocket toneAmber
class node_reasoning,node_rules,node_graph_analysis,node_workflow_service,node_analytics toneMint
class node_dashboard,node_api_client toneRose
class node_mcp_server,node_mcp_tools,node_app,node_user toneIndigo
```

## Components

### Runtime observation

- [SDK tracing](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/nexarch-sdk/nexarch/tracing/span.py): `nexarch-sdk/nexarch/tracing/span.py`
- [Library hooks](https://github.com/gitbyjay25/hackvilla-uk04/tree/main/nexarch-sdk/nexarch/instrumentation): `nexarch-sdk/nexarch/instrumentation`
- [HTTP exporter](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/nexarch-sdk/nexarch/exporters/http.py): `nexarch-sdk/nexarch/exporters/http.py`

### Ingestion and streaming

- [FastAPI application](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/main.py): `Server/main.py`
- [Telemetry ingestion](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/api/ingest.py): `Server/api/ingest.py`
- [Span persistence](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/services/ingest_service.py): `Server/services/ingest_service.py`
- [Platform database](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/db/models.py): `Server/db/models.py`
- [Streaming pipeline](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/pipeline.py): `Server/streaming/pipeline.py`
- [Graph transforms](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/transforms/graph_builder.py): `Server/streaming/transforms/graph_builder.py`
- [Live updates](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/streaming/websocket.py): `Server/streaming/websocket.py`

### Architecture intelligence

- [Workflow reasoning](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/langgraph_pipeline.py): `Server/reasoning/langgraph_pipeline.py`
- [Issue rules](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/rules.py): `Server/reasoning/rules.py`
- [Graph analysis](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/reasoning/graph_analysis.py): `Server/reasoning/graph_analysis.py`
- [Workflow generation](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/services/workflow_generator.py): `Server/services/workflow_generator.py`
- [Project analytics](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/services/project_analytics_service.py): `Server/services/project_analytics_service.py`

### Product interfaces

- [Web dashboard](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/frontend/src/app/dashboard/page.js): `frontend/src/app/dashboard/page.js`
- [Frontend API client](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/frontend/src/lib/api-client.js): `frontend/src/lib/api-client.js`

### External access

- [MCP server](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/mcp_server/server.py): `Server/mcp_server/server.py`
- [Architecture tools](https://github.com/gitbyjay25/hackvilla-uk04/blob/main/Server/mcp_server/tools.py): `Server/mcp_server/tools.py`

### Other components

- **Instrumented application**
- **Team member**

## Connections

- Instrumented application → Library hooks: runs with
- Library hooks → SDK tracing: captures spans
- SDK tracing → HTTP exporter: exports telemetry
- HTTP exporter → Telemetry ingestion: posts spans
- FastAPI application → Telemetry ingestion: registers routes
- Telemetry ingestion → Span persistence: stores spans
- Span persistence → Platform database: writes spans
- FastAPI application → Streaming pipeline: starts pipeline
- Streaming pipeline → Graph transforms: builds graph tables
- Streaming pipeline → Live updates: pushes updates
- Workflow reasoning → Issue rules: detects issues
- Workflow reasoning → Graph analysis: analyzes graph
- Team member → Web dashboard: views insights
- Web dashboard → Frontend API client: requests data
- Frontend API client → FastAPI application: calls endpoints
- MCP server → Architecture tools: dispatches tools