EDP
platform-analytics-agent
Natural language analytics backend

platform-analytics-agent

This repository is part of the Enterprise Data Platform. For the full project overview, architecture diagram, and build order, start there.

FastAPIClaudeAthenaS3StreamlitECS
Complete analytics serving architecture A single left-to-right path: frontend choice, shared backend, governed reasoning, data query, stakeholder-ready output. User and frontends Stakeholder business question Frontend choice Streamlit UI HTML dashboard Slack MCP Shared analytics API FastAPI backend session state agent orchestration export packaging Governed reasoning Schema context Claude SQL Guardrails Correction loop regenerate on mismatch Data query Gold S3 Athena S3 Audit metadata Output Answer insight KPI cards chart table PDF + CSV question build prompt mismatch validated SQL result
Presentation stays thinStreamlit, HTML, and Slack collect questions and display the same response contract from FastAPI.
FastAPI is the control pointThe backend owns session state, schema context, orchestration, exports, cost, verdicts, and audit metadata.
Correction is explicitThe loop compares generated SQL intent with the original question and regenerates before Athena runs when needed.
One answer contractThe output contains the stakeholder-facing result: insight, KPI cards, chart, table, PDF, CSV, cost, and verdict.
Request flow diagrams

Three front doors, one governed analytics brain

The Streamlit UI, custom HTML UI, and Slack/MCP gateway all converge on the same FastAPI analytics backend. The backend owns SQL generation, guardrail validation, intent verification, correction on mismatch, Athena execution, insight generation, export packaging, and audit logging.

Streamlit frontend

Stakeholder browser to Streamlit UI and FastAPI backend

The Streamlit page and FastAPI backend share one ECS container, so the UI hands the question to the backend through localhost before the governed agent loop begins.

Streamlit UI request flow Stakeholder AWS ALB Streamlit UI FastAPI backend Claude API Athena S3 Audit Streamlit and FastAPI run in the same ECS task 1. Open app 2. Forward UI request 3. Render question form 4. Submit question 5. Local backend call 6. Generate SQL SQL query 7. Validate guardrails 8. Infer SQL intent 9. Compare question vs intent Verdict + discrepancy detail Correction loop on mismatch 10. Regenerate corrected SQL Corrected SQL Validate corrected SQL 11. Run Athena query Rows, cost, execution ID 12. Write audit log 13. Render answer, chart, KPI cards, exports
Container boundaryStreamlit and FastAPI run in the same ECS task, so the UI can call the backend locally.
Governed SQLClaude generates SQL, then the backend validates it before Athena execution.
Correction loopIntent mismatch triggers regeneration and a second validation pass before data is queried.
Returned packageThe browser receives the answer, chart, KPI cards, table data, exports, cost, and audit verdict.
Custom HTML frontend

Standalone web dashboard to the existing analytics backend

The HTML dashboard is a separate ECS service. It serves static UI assets, proxies API calls to FastAPI, and preserves the backend reasoning loop without changing Streamlit.

Custom HTML web frontend flow Stakeholder AWS ALB HTML web ECS FastAPI backend Claude API Athena S3 Audit 1. Open web URL 2. Serve HTML/CSS/JS 3. Dashboard renders in browser 4. POST /api/ask/stream 5. Proxy to FastAPI 6. Generate SQL SQL query Validate guardrails 7. Verify SQL intent Verdict + discrepancy detail Correction loop on mismatch 8. Regenerate corrected SQL Corrected SQL 9. Execute governed query Rows and scan cost 10. Audit request 11. Stream answer JSON 12. KPI cards, chart, CSV/PDF export
Separate frontendThe HTML service owns presentation and proxies analytics calls to the existing FastAPI backend.
Same API behaviorIt uses the same question, SQL, result, report, and audit contract as Streamlit.
Correction loopMismatch handling remains in the backend, so the richer UI does not weaken governance.
Stakeholder exportsThe frontend can emphasize KPI cards, polished charts, CSV table downloads, and PDF reports.
Slack / MCP gateway

Slack entry point for governed analytics tools

The Slack gateway is another front door. Slack messages reach the MCP gateway, the gateway invokes analytics tools against the same FastAPI backend, and responses return to Slack with auditability preserved.

Slack MCP analytics flow Stakeholder Slack MCP gateway FastAPI backend Claude API Athena S3 Audit 1. Ask in Slack 2. Event/tool request 3. Verify Slack + route MCP tool 4. Call analytics API 5. Generate SQL SQL query Validate guardrails 6. Intent verification Verdict + discrepancy detail Correction loop on mismatch 7. Regenerate SQL Corrected SQL 8. Query Gold tables Rows and metrics 9. Write audit log 10. Tool result 11. Slack response payload 12. Answer in channel
Slack as a front doorThe MCP gateway turns Slack interaction into an analytics API request.
Backend ownershipQuestion interpretation, SQL generation, validation, and execution stay inside the agent backend.
Correction loopThe same mismatch correction path runs before any query reaches the Gold layer.
Slack-native returnThe gateway packages the answer, metrics, assumptions, report assets, and audit context for Slack.
Shared backend contractEach frontend sends questions to the same governed FastAPI API surface.
Same analytics brainStreamlit, HTML, and Slack all converge on the same FastAPI backend and governance checks.
Correction before executionThe backend validates SQL and corrects intent mismatch before querying Athena.
Audit by defaultEach interface preserves request metadata, cost, verdict, and query audit trails.
Visual ownership map

What this repo owns

The repository owns the analytics API, the reasoning and verification loop, the stakeholder answer package, and the audit trail that supports governance across all user-facing channels.

API surface/ask, /ask/stream, /health, /report/pdf
Reasoning loopGenerate SQL, validate guardrails, verify intent, correct mismatch
Data planeAthena over Gold marts with cost and row evidence
UX surfacesStreamlit UI, custom HTML dashboard, Slack/MCP gateway
ExportsKPI cards, charts, CSV tables, PDF reports, downloadable logs
Evidence trailSQL, execution ID, cost, verdict, and S3 audit metadata

Governed generation

Question Claude SQL The model generates SQL from preloaded Gold schemas, not from direct ad hoc table discovery.

Guardrail gate

Draft SQL SELECTGold only Run SQL is checked before Athena sees it: read-only query, allowed database, safe limits, and known schema.

Intent verification

Originalquestion Inferredintent Verdictmatch? The backend compares the user question to SQL intent and can regenerate before execution.

Business answer package

Insight→KPI cards→Chart→Table→PDF/CSV
Each frontend should show the same evidence package, even when the presentation differs.

Export paths

Rows→CSV Narrative→PDF Session→Log
Stakeholders get shareable outputs without needing Athena, SQL, or repo access.

Audit trail

Request Verdict S3 Questions, generated SQL, mismatch verdicts, execution IDs, and costs are recorded for review.
Runtime view

Deployment surfaces

The README remains the source of truth for commands. This page keeps the operational shape visible at a glance.

Local devFastAPI on port 8080; frontend surfaces proxy requests to the backend.
AWS devALB routes traffic to ECS services for Streamlit, HTML web, Slack gateway, and API.
Data dependenciesGlue Gold catalog, Athena workgroup, S3 result bucket, Claude API key in SSM.

Detailed setup commands, environment variables, and troubleshooting live in the rendered README.md.