How gtbitsofgood/bog-analytics works
Project type and purpose
• This is a full-stack, monorepo analytics platform (“Bits of Good Analytics”) with four core deliverables:
• A Python/Streamlit Dashboard for data visualization
• A TypeScript “Analytics Processing API” (serverless on Netlify) that ingests and stores events
• An NPM “Package” client library (“bog-analytics”) to instrument front-ends and call the API
• A Next.js “Portal” for project and event-type management, backed by its own Node/MongoDB server
High-level components (from file tree & README)
• Dashboard: dashboard/ (Streamlit app, Python, connects to API via HTTP)
• API: api/ (TypeScript, Netlify functions, models, controllers, migrations, connects to MongoDB analytics DB)
• Package: package/ (TypeScript library, wraps API calls, exposes event-logging functions)
• Portal: portal/ (Next.js + React front end under portal/src/app, plus server code under portal/server, authenticates via MongoDB portal DB)
• Deletion-policy service: deletion-policy/ (TypeScript cron job/Netlify function for GDPR deletions)
• Probe action: probe-action/ (GitHub Action to health-check or smoke-test the API)
• Supporting infra: Docker Compose files for local dev (docker-compose.yml, etc.)
Core data flows & relationships
1. Instrumented client (any Bits of Good project, e.g. examples/example-project) installs bog-analytics package → calls analytics API HTTP endpoints → events are validated, processed and stored in the analytics MongoDB.
2. Deletion-policy service (cron job) calls API’s GDPR endpoints to permanently delete user data per policy.
3. Portal UI & server call their own MongoDB (portal DB) for user/project metadata, and may also call the analytics API to surface event-type counts or example payloads.
4. Dashboard (Streamlit) calls the analytics API to fetch aggregated event data for UI charts.
5. Probe-action runs periodically (GitHub Action) to call health & sample-event endpoints on the analytics API.
Architectural patterns & design principles
• Microservices style: separate deployments for API, Portal, Dashboard, Deletion job, Probe action
• Serverless functions (Netlify) for API endpoints
• Single shared analytics MongoDB for event storage, separate portal MongoDB for auth & metadata
• NPM package as a thin client SDK layer over REST API
• Clear MVC in the API: models/, controllers/, routes.ts, middleware/
• Next.js App Router for Portal front end + serverless API routes