# jhonnycoder/ai-management-consulting architecture

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

- Interactive diagram: https://gitdiagram.com/jhonnycoder/ai-management-consulting
- Repository: https://github.com/jhonnycoder/ai-management-consulting

## Overview

1. **Overall shape**
   - This repo is split into three clear boundaries: a **browser frontend**, a **FastAPI backend**, and a **pure analytics engine** in `analytics_pipeline/`.
   - The main runtime flow is: **CSV upload → backend orchestration → multi-layer analytics pipeline → LLM synthesis → JSON response → dashboard rendering**.

2. **Frontend boundary**
   - `frontend/` is a static, client-side app built with **vanilla JavaScript, HTML, and CSS**.
   - It handles file selection/upload UX, renders the dashboard, and draws visual output with **Chart.js** and **Three.js**.
   - The frontend is presentation-only: it does not perform the analytics itself, but consumes the backend JSON API and turns it into charts, diagnostics, and narrative cards.

3. **Backend API boundary**
   - `backend/main.py` is the FastAPI entrypoint and the HTTP integration layer.
   - This layer owns request handling, static hosting, and translating uploaded data into calls to the analytics engine.
   - `backend/schemas/analytics_response.py` defines the API response contract, while `backend/mappers.py` converts internal pipeline state into the API shape and sanitizes problematic numeric values.

4. **CSV ingestion and local file handling**
   - User datasets are uploaded to the backend and stored under `backend/uploads/`.
   - The backend treats uploaded files as local processing inputs rather than streaming sources.
   - UUID-style naming and sanitization are part of the boundary to keep uploads isolated from the rest of the app.

5. **Core analytics engine**
   - `analytics_pipeline/` is the heart of the system and is intentionally separated from web concerns.
   - `analytics_pipeline/orchestrator.py` coordinates the pipeline execution and acts as the registry/runner for the analytical stages.
   - `analytics_pipeline/schema.py`, `config.py`, `exceptions.py`, and `utils.py` provide shared validation, settings, error types, and helpers used across layers.

6. **Pipeline layer structure**
   - The analysis is organized into named stages under `analytics_pipeline/layers/`, roughly flowing from low-level computation to executive output:
     - `raw_computation.py`: profiling, correlations, health metrics, and chart-friendly raw signals
     - `normalization.py`: scaling and taxonomy of signals
     - `structuring.py`: contextual synthesis and theme formation
     - `reasoning.py`: stability and cross-theme logic
     - `decision.py`: executive synthesis and confidence scoring
     - `output.py`: narrative insights and recommendations
   - This layer stack is the main architectural driver for any diagram of the analytics subsystem.

7. **LLM synthesis boundary**
   - `analytics_pipeline/ai_readiness.py` prepares the pipeline output into an LLM-ready context.
   - `backend/ai_client.py` is the external model integration layer, supporting **Groq** and a local **Ollama** fallback.
   - The LLM is used only after deterministic analytics have already reduced the dataset into structured signals; it does not replace the pipeline, it summarizes it into human-readable executive guidance.

8. **Data products and response flow**
   - The backend returns a structured JSON payload that includes diagnostics, chart data, and AI-generated summaries.
   - The frontend uses that payload to render score cards, narrative sections, and multiple visualization types depending on the detected data shape.
   - The architecture therefore has two output planes: **machine-readable analytics data** and **human-readable strategic recommendations**.

9. **Observability and reliability**
   - `analytics_pipeline/logger.py` and backend logging write structured pipeline logs to `backend/logs/pipeline.log`.
   - Logging is designed to keep the terminal quiet while preserving detailed stage-by-stage traceability.
   - The repo also emphasizes defensive handling for NaN/Infinity, timeouts around model calls, and custom exceptions for pipeline failures.

10. **Testing and separation of concerns**
   - The `analytics_pipeline/tests/` suite tests layers, orchestration, and serialization independently of the UI.
   - This reinforces the separation between:
     - **analytics logic**
     - **API/mapping logic**
     - **presentation logic**
   - For an architecture diagram, it is useful to show the pipeline as a standalone domain module invoked by the backend, not as code embedded in the frontend.

11. **Deployment/runtime context**
   - The stack is Python 3.10+ on the backend, served with FastAPI/Uvicorn, and a browser-based static frontend.
   - The system can operate with an external LLM API or a local Ollama runtime, making the AI layer an optional external dependency rather than a hard-coded single vendor integration.

Main entry points: [`analytics_pipeline/orchestrator.py`](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/orchestrator.py) (Orchestrator), [`backend/main.py`](https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/main.py) (API entry), [`frontend/script.js`](https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/script.js) (Client app), [`backend/ai_client.py`](https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/ai_client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_index["UI shell<br/>static page<br/>[index.html]"]
  node_frontend_script["Client app<br/>js app<br/>[script.js]"]
  node_frontend_style["Styles<br/>css<br/>[style.css]"]
  node_frontend_background["Background<br/>js worker<br/>[background.js]"]
end

subgraph group_backend["Backend API"]
  node_backend_main["API entry<br/>FastAPI app<br/>[main.py]"]
  node_backend_mappers["Response map<br/>mapper<br/>[mappers.py]"]
  node_backend_ai_client["LLM client<br/>model adapter<br/>[ai_client.py]"]
  node_backend_schema["API schema<br/>response contract"]
end

subgraph group_analytics["Analytics Engine"]
  node_orchestrator{{"Orchestrator<br/>pipeline runner<br/>[orchestrator.py]"}}
  node_pipeline_schema["Domain schema<br/>validation model<br/>[schema.py]"]
  node_pipeline_config["Config<br/>settings<br/>[config.py]"]
  node_pipeline_exceptions["Errors<br/>exceptions<br/>[exceptions.py]"]
  node_pipeline_utils["Utils<br/>helpers<br/>[utils.py]"]
  node_pipeline_logger["Logging<br/>logger<br/>[logger.py]"]
  node_layer_raw["Raw signals<br/>analysis stage<br/>[raw_computation.py]"]
  node_layer_norm["Normalize<br/>analysis stage<br/>[normalization.py]"]
  node_layer_struct["Structure<br/>analysis stage<br/>[structuring.py]"]
  node_layer_reason["Reason<br/>analysis stage<br/>[reasoning.py]"]
  node_layer_decision["Decide<br/>analysis stage<br/>[decision.py]"]
  node_layer_output["Output<br/>analysis stage<br/>[output.py]"]
  node_ai_readiness["LLM context<br/>prep layer<br/>[ai_readiness.py]"]
end

node_llm_runtime(("Groq/Ollama<br/>external model"))

node_frontend_index -->|"loads"| node_frontend_script
node_frontend_script -->|"uploads / queries"| node_backend_main
node_frontend_script -.->|"delegates"| node_frontend_background
node_frontend_script -.->|"renders with"| node_frontend_style
node_backend_main -->|"invokes"| node_orchestrator
node_backend_main -->|"maps"| node_backend_mappers
node_backend_main -->|"returns"| node_backend_schema
node_backend_main -->|"calls"| node_backend_ai_client
node_orchestrator -->|"validates"| node_pipeline_schema
node_orchestrator -->|"reads"| node_pipeline_config
node_orchestrator -.->|"uses"| node_pipeline_utils
node_orchestrator -.->|"raises"| node_pipeline_exceptions
node_orchestrator -.->|"logs"| node_pipeline_logger
node_orchestrator -->|"starts"| node_layer_raw
node_layer_raw -->|"feeds"| node_layer_norm
node_layer_norm -->|"feeds"| node_layer_struct
node_layer_struct -->|"feeds"| node_layer_reason
node_layer_reason -->|"feeds"| node_layer_decision
node_layer_decision -->|"feeds"| node_layer_output
node_layer_output -->|"prepares"| node_ai_readiness
node_ai_readiness -->|"summarizes via"| node_backend_ai_client
node_backend_ai_client -->|"uses"| node_llm_runtime
node_backend_mappers -->|"conforms to"| node_backend_schema
node_backend_main -.->|"serves JSON to"| node_frontend_script

click node_frontend_index "https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/index.html"
click node_frontend_script "https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/script.js"
click node_frontend_style "https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/style.css"
click node_frontend_background "https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/background.js"
click node_backend_main "https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/main.py"
click node_backend_mappers "https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/mappers.py"
click node_backend_ai_client "https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/ai_client.py"
click node_backend_schema "https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/schemas/analytics_response.py"
click node_orchestrator "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/orchestrator.py"
click node_pipeline_schema "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/schema.py"
click node_pipeline_config "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/config.py"
click node_pipeline_exceptions "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/exceptions.py"
click node_pipeline_utils "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/utils.py"
click node_pipeline_logger "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/logger.py"
click node_layer_raw "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/raw_computation.py"
click node_layer_norm "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/normalization.py"
click node_layer_struct "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/structuring.py"
click node_layer_reason "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/reasoning.py"
click node_layer_decision "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/decision.py"
click node_layer_output "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/output.py"
click node_ai_readiness "https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/ai_readiness.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_frontend_index,node_frontend_script,node_frontend_style,node_frontend_background toneBlue
class node_backend_main,node_backend_mappers,node_backend_ai_client,node_backend_schema toneAmber
class node_orchestrator,node_pipeline_schema,node_pipeline_config,node_pipeline_exceptions,node_pipeline_utils,node_pipeline_logger,node_layer_raw,node_layer_norm,node_layer_struct,node_layer_reason,node_layer_decision,node_layer_output,node_ai_readiness toneMint
class node_llm_runtime toneNeutral
```

## Components

### Frontend

Static browser UI for upload, dashboard rendering, and visualization

- [UI shell](https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/index.html): static page · Main HTML entrypoint for the browser app · `frontend/index.html`
- [Client app](https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/script.js): js app · Handles upload flow, API calls, and dashboard rendering · `frontend/script.js`
- [Styles](https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/style.css): css · Presentation and layout styling for the client UI · `frontend/style.css`
- [Background](https://github.com/jhonnycoder/ai-management-consulting/blob/main/frontend/background.js): js worker · Auxiliary browser-side logic for the frontend · `frontend/background.js`

### Backend API

FastAPI HTTP layer, response mapping, and model integration

- [API entry](https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/main.py): FastAPI app · HTTP entrypoint, request handling, and orchestration boundary · `backend/main.py`
- [Response map](https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/mappers.py): mapper · Converts pipeline output into API response shape and sanitizes values · `backend/mappers.py`
- [LLM client](https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/ai_client.py): model adapter · External model integration with Groq and Ollama fallback · `backend/ai_client.py`
- [API schema](https://github.com/jhonnycoder/ai-management-consulting/blob/main/backend/schemas/analytics_response.py): response contract · JSON response model for analytics results · `backend/schemas/analytics_response.py`

### Analytics Engine

Pure pipeline domain for deterministic analysis and synthesis

- [Orchestrator](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/orchestrator.py): pipeline runner · Coordinates analytics execution across the layer stack · `analytics_pipeline/orchestrator.py`
- [Domain schema](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/schema.py): validation model · Shared analytics data structures and validation rules · `analytics_pipeline/schema.py`
- [Config](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/config.py): settings · Runtime settings and pipeline configuration · `analytics_pipeline/config.py`
- [Errors](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/exceptions.py): exceptions · Custom failures used across the analytics domain · `analytics_pipeline/exceptions.py`
- [Utils](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/utils.py): helpers · Shared helper functions used by the pipeline · `analytics_pipeline/utils.py`
- [Logging](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/logger.py): logger · Structured pipeline logging and traceability · `analytics_pipeline/logger.py`
- [Raw signals](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/raw_computation.py): analysis stage · Profiling, correlations, and chart-friendly metrics · `analytics_pipeline/layers/raw_computation.py`
- [Normalize](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/normalization.py): analysis stage · Scaling and taxonomy of signals · `analytics_pipeline/layers/normalization.py`
- [Structure](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/structuring.py): analysis stage · Contextual synthesis and theme formation · `analytics_pipeline/layers/structuring.py`
- [Reason](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/reasoning.py): analysis stage · Stability checks and cross-theme logic · `analytics_pipeline/layers/reasoning.py`
- [Decide](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/decision.py): analysis stage · Executive synthesis and confidence scoring · `analytics_pipeline/layers/decision.py`
- [Output](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/layers/output.py): analysis stage · Narrative insights and recommendations · `analytics_pipeline/layers/output.py`
- [LLM context](https://github.com/jhonnycoder/ai-management-consulting/blob/main/analytics_pipeline/ai_readiness.py): prep layer · Shapes deterministic outputs into model-ready context · `analytics_pipeline/ai_readiness.py`

### Other components

- **Groq/Ollama**: external model · Optional external or local LLM runtime used for synthesis

## Connections

- UI shell → Client app: loads · Browser loads the client application
- Client app → API entry: uploads / queries · Client sends CSV uploads and requests analytics JSON
- Client app → Background: delegates · Client-side app uses auxiliary browser logic
- Client app → Styles: renders with · UI is presented through shared styling
- API entry → Orchestrator: invokes · API entrypoint dispatches datasets into the analytics pipeline
- API entry → Response map: maps · Transforms internal results into response payloads
- API entry → API schema: returns · HTTP responses follow the defined analytics contract
- API entry → LLM client: calls · Backend coordinates optional model synthesis
- Orchestrator → Domain schema: validates · Pipeline uses shared domain structures
- Orchestrator → Config: reads · Execution behavior is driven by pipeline settings
- Orchestrator → Utils: uses · Shared helper functions support orchestration
- Orchestrator → Errors: raises · Domain failures propagate as custom exceptions
- Orchestrator → Logging: logs · Stage-by-stage traceability is emitted during execution
- Orchestrator → Raw signals: starts · Pipeline begins with raw signal computation
- Raw signals → Normalize: feeds · Raw metrics are standardized and categorized
- Normalize → Structure: feeds · Normalized signals become structured themes
- Structure → Reason: feeds · Themes are evaluated for consistency and logic
- Reason → Decide: feeds · Reasoned findings inform executive decisions
- Decide → Output: feeds · Decisions are converted into recommendations and narratives
- Output → LLM context: prepares · Final deterministic output is packaged for model context
- LLM context → LLM client: summarizes via · Prepared context is sent to the model adapter for synthesis
- LLM client → Groq/Ollama: uses · Adapter can call either hosted or local model runtime
- Response map → API schema: conforms to · Mapped payloads are shaped to the API contract
- API entry → Client app: serves JSON to · Frontend consumes analytics API output