jhonnycoder/ai-management-consulting

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.