How parthtyagi9/scanalytics works
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: controller Web Boundary · (routes) Product Routes · service Domain Services · DashboardController.java Dashboard API
Components 21
Frontend
Next.js app router UI and server routes
- Next.js App · App Router-based product and marketing UI
frontend/app - Product Routes · Dashboard, insights, integration, observability, onboarding, projects, and success flows
frontend/app/(routes) - Auth Pages · Login and registration screens
frontend/app/auth - Chat Proxy · Browser-facing API route that adapts chat requests to the backend
frontend/app/api/chat/route.ts - UI Shell · Shared sidebar layout and reusable UI components
frontend/components - Success Template · 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 · Main server application and web API entrypoint
backend-spring/src/main/java/com/scanalytics/ScanalyticsApplication.java - Web Boundary · HTTP controllers and request handling configuration
backend-spring/src/main/java/com/scanalytics/controller - Track API · Accepts analytics events from clients or SDKs
backend-spring/src/main/java/com/scanalytics/controller/TrackController.java - Dashboard API · Serves dashboard data and aggregated metrics
backend-spring/src/main/java/com/scanalytics/controller/DashboardController.java - Insights API · Exposes insight generation and metric proposal endpoints
backend-spring/src/main/java/com/scanalytics/controller/InsightsController.java - Onboarding API · Handles project creation and initial setup flows
backend-spring/src/main/java/com/scanalytics/controller/OnboardingController.java - Chat API · Backend chat and assistant interaction endpoint
backend-spring/src/main/java/com/scanalytics/controller/ChatController.java - Domain Services · Business logic for events, dashboards, projects, and AI
backend-spring/src/main/java/com/scanalytics/service - AI Engine · Isolates external LLM or AI provider access
backend-spring/src/main/java/com/scanalytics/service/AiEngineService.java - Persistence Layer · JPA repositories and domain entities
backend-spring/src/main/java/com/scanalytics/repository - Init and Seed · Schema initialization and seed data on application startup
backend-spring/src/main/java/com/scanalytics/config/DatabaseInitConfig.java - API Key Guard · Cross-cutting request protection at the web boundary
backend-spring/src/main/java/com/scanalytics/security/ApiKeyInterceptor.java - Error Handler · Centralized API error translation
backend-spring/src/main/java/com/scanalytics/exception/GlobalExceptionHandler.java - App Config · CORS, web config, and application settings
backend-spring/src/main/resources/application.yml - PostgreSQL · Stores projects, events, and insight configs
backend-spring/src/main/resources/schema.sql
Connections 27
- 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