# parthtyagi9/scanalytics architecture

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

- Interactive diagram: https://gitdiagram.com/parthtyagi9/scanalytics
- Repository: https://github.com/parthtyagi9/scanalytics

## Overview

1. **Repository shape**
   - This is a full-stack monorepo with a **Java/Spring Boot backend** in `backend-spring` and a **Next.js/React frontend** in `frontend`.
   - The README’s Python/FastAPI references appear outdated; the actual implementation is Spring Boot on the server side.

2. **Backend boundary**
   - The backend is organized as a classic layered Spring application: **controllers → services → repositories → database models**.
   - `ScanalyticsApplication` is the entry point, with `pom.xml` defining the build and `application.yml` holding runtime configuration.

3. **HTTP/API layer**
   - Controllers are split by domain: `TrackController`, `DashboardController`, `InsightsController`, `OnboardingController`, and `ChatController`.
   - This suggests separate API surfaces for event ingestion, dashboard retrieval, insight generation, project setup, and AI/chat interactions.
   - `CorsConfig` and `WebConfig` define request handling cross-cutting concerns at the web boundary.

4. **Core domain model**
   - The persistence model centers on three entities: `Project`, `AnalyticsEvent`, and `InsightConfig`.
   - `Project` represents a customer/workspace, `AnalyticsEvent` stores tracked behavior, and `InsightConfig` holds dashboard/analysis definitions generated or configured per project.

5. **Persistence and storage**
   - `ProjectRepository`, `EventRepository`, and `InsightConfigRepository` indicate JPA-style access to a relational database, almost certainly PostgreSQL given the README and `schema.sql`.
   - `DatabaseInitConfig` and `SeedDataRunner` show the app initializes schema/data on startup, which is important for local bootstrapping and prototype/demo deployments.

6. **Event ingestion flow**
   - The likely primary data flow is: client or SDK sends an event to `TrackController` → `EventService` validates/stores it → repository writes it to the database.
   - `EventCreateRequest` and `AnalyticsEvent` indicate the backend accepts structured event payloads, probably with flexible/custom properties for analytics use cases.

7. **Dashboard and insights flow**
   - `DashboardController` and `InsightsController` likely read stored events and insight configuration through `DashboardService`.
   - `DashboardResponse`, `MetricProposal`, and `MetricSpec` suggest the backend can both render existing metrics and propose or define new ones dynamically.

8. **AI/LLM subsystem**
   - `AiEngineService` is the backend’s AI boundary.
   - Based on the README, this service likely wraps an external LLM provider to generate custom analytics code, chat responses, metric suggestions, or insight SQL.
   - The exact provider is not visible in the tree, so the architectural point is that AI is isolated behind a dedicated service rather than embedded in controllers.

9. **Security and request protection**
   - `ApiKeyInterceptor` is the main security boundary in the backend, implying API-key-based access control rather than full user authentication.
   - `GlobalExceptionHandler` centralizes API error translation, so controllers and services can fail consistently without duplicating error handling.

10. **Frontend application structure**
    - The frontend uses the **Next.js App Router** with route groups for the marketing site, auth pages, and the product app.
    - Main app areas are `dashboard`, `insights`, `integration`, `observability`, `onboarding`, `projects`, and `success`, which map directly to product workflows.
    - Shared UI is composed from reusable components in `components/` and `components/ui/`, with Tailwind-based styling and a sidebar layout for the logged-in app shell.

11. **Frontend-to-backend interaction**
    - `frontend/app/api/chat/route.ts` is a server-side API route, likely acting as a proxy or adapter between the browser and backend chat endpoint.
    - The frontend therefore has both direct rendered pages and a small server API boundary, which helps hide backend URLs or handle request shaping.

12. **User journey and functional flow**
    - The product flow is: browse landing pages → register/login → onboarding/project creation → view integration instructions → send tracked events → inspect dashboard/insights → use chat for AI assistance.
    - The `success/templates` area suggests the app can present generated output after onboarding or project setup, consistent with the “custom analytics” positioning.

13. **Deployment and runtime clues**
    - `Procfile` and `system.properties` indicate the backend is prepared for platform deployment with a fixed Java runtime.
    - The frontend is standard Node/Next.js, while the backend is Maven-built Java, so deployment is split across two runtimes with a database in the middle.

14. **What to draw in an architecture diagram**
    - Show three main tiers: **browser/frontend**, **Spring Boot API**, and **PostgreSQL**.
    - Add a side boundary for **AI/LLM services** behind `AiEngineService`.
    - Annotate the backend with **API key interception**, **startup seed/init**, and **global exception handling** as cross-cutting concerns.

Main entry points: [`backend-spring/src/main/java/com/scanalytics/controller`](https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/controller) (Web Boundary), [`frontend/app/(routes)`](https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app/(routes)) (Product Routes), [`backend-spring/src/main/java/com/scanalytics/service`](https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/service) (Domain Services), [`backend-spring/src/main/java/com/scanalytics/controller/DashboardController.java`](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/DashboardController.java) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js App<br/>Next.js frontend"]
  node_frontend_routes["Product Routes<br/>route pages"]
  node_frontend_auth["Auth Pages<br/>auth routes"]
  node_frontend_chat_api["Chat Proxy<br/>server route<br/>[route.ts]"]
  node_frontend_shell["UI Shell<br/>layout/components"]
  node_frontend_template["Success Template<br/>generated UI<br/>[base_analytics.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_app["Spring Boot API<br/>Spring Boot backend"]
  node_backend_web["Web Boundary<br/>controllers/config"]
  node_backend_track["Track API<br/>ingestion controller"]
  node_backend_dashboard["Dashboard API<br/>read controller"]
  node_backend_insights["Insights API<br/>analysis controller"]
  node_backend_onboarding["Onboarding API<br/>setup controller"]
  node_backend_chat["Chat API<br/>ai controller"]
  node_backend_services["Domain Services<br/>service layer"]
  node_backend_ai["AI Engine<br/>llm boundary"]
  node_backend_data[("Persistence Layer<br/>repositories/models")]
  node_backend_init["Init and Seed<br/>startup bootstrap"]
  node_backend_security{{"API Key Guard<br/>security/interceptor"}}
  node_backend_errors{{"Error Handler<br/>exception handling"}}
  node_backend_config["App Config<br/>runtime config<br/>[application.yml]"]
  node_backend_db[("PostgreSQL<br/>relational database<br/>[schema.sql]")]
end

subgraph group_infra["Runtime"]
end

node_frontend_app -->|"renders"| node_frontend_routes
node_frontend_app -->|"renders"| node_frontend_auth
node_frontend_routes -->|"uses"| node_frontend_shell
node_frontend_auth -->|"uses"| node_frontend_shell
node_frontend_routes -->|"shows"| node_frontend_template
node_frontend_chat_api -.->|"proxies"| node_backend_chat
node_frontend_routes -.->|"fetches"| node_backend_dashboard
node_frontend_routes -.->|"fetches"| node_backend_insights
node_frontend_routes -.->|"fetches"| node_backend_onboarding
node_backend_app -->|"hosts"| node_backend_web
node_backend_web -->|"routes"| node_backend_track
node_backend_web -->|"routes"| node_backend_dashboard
node_backend_web -->|"routes"| node_backend_insights
node_backend_web -->|"routes"| node_backend_onboarding
node_backend_web -->|"routes"| node_backend_chat
node_backend_web -->|"intercepts"| node_backend_security
node_backend_web -->|"normalizes"| node_backend_errors
node_backend_track -->|"delegates"| node_backend_services
node_backend_dashboard -->|"delegates"| node_backend_services
node_backend_insights -->|"delegates"| node_backend_services
node_backend_onboarding -->|"delegates"| node_backend_services
node_backend_chat -->|"uses"| node_backend_ai
node_backend_services -->|"reads/writes"| node_backend_data
node_backend_services -->|"invokes"| node_backend_ai
node_backend_init -->|"boots"| node_backend_db
node_backend_data -->|"stores"| node_backend_db
node_backend_app -->|"loads"| node_backend_config

click node_frontend_app "https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app"
click node_frontend_routes "https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app/(routes)"
click node_frontend_auth "https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app/auth"
click node_frontend_chat_api "https://github.com/parthtyagi9/scanalytics/blob/main/frontend/app/api/chat/route.ts"
click node_frontend_shell "https://github.com/parthtyagi9/scanalytics/tree/main/frontend/components"
click node_frontend_template "https://github.com/parthtyagi9/scanalytics/blob/main/frontend/app/(routes)/success/templates/base_analytics.tsx"
click node_backend_app "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/ScanalyticsApplication.java"
click node_backend_web "https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/controller"
click node_backend_track "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/TrackController.java"
click node_backend_dashboard "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/DashboardController.java"
click node_backend_insights "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/InsightsController.java"
click node_backend_onboarding "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/OnboardingController.java"
click node_backend_chat "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/ChatController.java"
click node_backend_services "https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/service"
click node_backend_ai "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/service/AiEngineService.java"
click node_backend_data "https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/repository"
click node_backend_init "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/config/DatabaseInitConfig.java"
click node_backend_security "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/security/ApiKeyInterceptor.java"
click node_backend_errors "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/exception/GlobalExceptionHandler.java"
click node_backend_config "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/resources/application.yml"
click node_backend_db "https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/resources/schema.sql"

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_app,node_frontend_routes,node_frontend_auth,node_frontend_chat_api,node_frontend_shell,node_frontend_template toneBlue
class node_backend_app,node_backend_web,node_backend_track,node_backend_dashboard,node_backend_insights,node_backend_onboarding,node_backend_chat,node_backend_services,node_backend_ai,node_backend_data,node_backend_init,node_backend_security,node_backend_errors,node_backend_config,node_backend_db toneAmber
```

## Components

### Frontend

Next.js app router UI and server routes

- [Next.js App](https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app): Next.js frontend · App Router-based product and marketing UI · `frontend/app`
- [Product Routes](https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app/(routes)): route pages · Dashboard, insights, integration, observability, onboarding, projects, and success flows · `frontend/app/(routes)`
- [Auth Pages](https://github.com/parthtyagi9/scanalytics/tree/main/frontend/app/auth): auth routes · Login and registration screens · `frontend/app/auth`
- [Chat Proxy](https://github.com/parthtyagi9/scanalytics/blob/main/frontend/app/api/chat/route.ts): server route · Browser-facing API route that adapts chat requests to the backend · `frontend/app/api/chat/route.ts`
- [UI Shell](https://github.com/parthtyagi9/scanalytics/tree/main/frontend/components): layout/components · Shared sidebar layout and reusable UI components · `frontend/components`
- [Success Template](https://github.com/parthtyagi9/scanalytics/blob/main/frontend/app/(routes)/success/templates/base_analytics.tsx): generated UI · Post-setup success and template presentation · `frontend/app/(routes)/success/templates/base_analytics.tsx`

### Backend

Spring Boot API, services, persistence, and runtime concerns

- [Spring Boot API](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/ScanalyticsApplication.java): Spring Boot backend · Main server application and web API entrypoint · `backend-spring/src/main/java/com/scanalytics/ScanalyticsApplication.java`
- [Web Boundary](https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/controller): controllers/config · HTTP controllers and request handling configuration · `backend-spring/src/main/java/com/scanalytics/controller`
- [Track API](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/TrackController.java): ingestion controller · Accepts analytics events from clients or SDKs · `backend-spring/src/main/java/com/scanalytics/controller/TrackController.java`
- [Dashboard API](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/DashboardController.java): read controller · Serves dashboard data and aggregated metrics · `backend-spring/src/main/java/com/scanalytics/controller/DashboardController.java`
- [Insights API](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/InsightsController.java): analysis controller · Exposes insight generation and metric proposal endpoints · `backend-spring/src/main/java/com/scanalytics/controller/InsightsController.java`
- [Onboarding API](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/OnboardingController.java): setup controller · Handles project creation and initial setup flows · `backend-spring/src/main/java/com/scanalytics/controller/OnboardingController.java`
- [Chat API](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/controller/ChatController.java): ai controller · Backend chat and assistant interaction endpoint · `backend-spring/src/main/java/com/scanalytics/controller/ChatController.java`
- [Domain Services](https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/service): service layer · Business logic for events, dashboards, projects, and AI · `backend-spring/src/main/java/com/scanalytics/service`
- [AI Engine](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/service/AiEngineService.java): llm boundary · Isolates external LLM or AI provider access · `backend-spring/src/main/java/com/scanalytics/service/AiEngineService.java`
- [Persistence Layer](https://github.com/parthtyagi9/scanalytics/tree/main/backend-spring/src/main/java/com/scanalytics/repository): repositories/models · JPA repositories and domain entities · `backend-spring/src/main/java/com/scanalytics/repository`
- [Init and Seed](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/config/DatabaseInitConfig.java): startup bootstrap · Schema initialization and seed data on application startup · `backend-spring/src/main/java/com/scanalytics/config/DatabaseInitConfig.java`
- [API Key Guard](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/security/ApiKeyInterceptor.java): security/interceptor · Cross-cutting request protection at the web boundary · `backend-spring/src/main/java/com/scanalytics/security/ApiKeyInterceptor.java`
- [Error Handler](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/java/com/scanalytics/exception/GlobalExceptionHandler.java): exception handling · Centralized API error translation · `backend-spring/src/main/java/com/scanalytics/exception/GlobalExceptionHandler.java`
- [App Config](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/resources/application.yml): runtime config · CORS, web config, and application settings · `backend-spring/src/main/resources/application.yml`
- [PostgreSQL](https://github.com/parthtyagi9/scanalytics/blob/main/backend-spring/src/main/resources/schema.sql): relational database · Stores projects, events, and insight configs · `backend-spring/src/main/resources/schema.sql`

## Connections

- Next.js App → Product Routes: renders · The app router serves product routes
- Next.js App → Auth Pages: renders · The app router serves auth pages
- Product Routes → UI Shell: uses · Product pages share sidebar and UI components
- Auth Pages → UI Shell: uses · Auth pages reuse shared form and UI primitives
- Product Routes → Success Template: shows · Success flow can present generated templates
- Chat Proxy → Chat API: proxies · Frontend server route forwards chat traffic to backend
- Product Routes → Dashboard API: fetches · Dashboard pages consume backend metrics and summaries
- Product Routes → Insights API: fetches · Insights pages consume metric proposals and analysis data
- Product Routes → Onboarding API: fetches · Onboarding pages create and configure projects
- Spring Boot API → Web Boundary: hosts · Application boots the web/API layer
- Web Boundary → Track API: routes · Event ingestion endpoint
- Web Boundary → Dashboard API: routes · Dashboard read endpoint
- Web Boundary → Insights API: routes · Insights and proposal endpoints
- Web Boundary → Onboarding API: routes · Project setup endpoint
- Web Boundary → Chat API: routes · Chat assistant endpoint
- Web Boundary → API Key Guard: intercepts · API key enforcement sits at request boundary
- Web Boundary → Error Handler: normalizes · Exceptions are translated into API responses
- Track API → Domain Services: delegates · Ingestion controller delegates to event service
- Dashboard API → Domain Services: delegates · Dashboard reads are handled in services
- Insights API → Domain Services: delegates · Insights generation is orchestrated in services
- Onboarding API → Domain Services: delegates · Project setup and creation use service logic
- Chat API → AI Engine: uses · Chat controller reaches the AI boundary through service layer
- Domain Services → Persistence Layer: reads/writes · Business logic persists and queries domain data
- Domain Services → AI Engine: invokes · Services call AI engine for suggestions and responses
- Init and Seed → PostgreSQL: boots · Startup bootstrap initializes schema and seed data
- Persistence Layer → PostgreSQL: stores · Repositories and models map onto the relational database
- Spring Boot API → App Config: loads · Application uses runtime configuration and web settings
