# prasadclasher/pricing-app architecture

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

- Interactive diagram: https://gitdiagram.com/prasadclasher/pricing-app
- Repository: https://github.com/prasadclasher/pricing-app

## Overview

1. **Overall shape**
   - This is a two-tier pricing application: a **React/Vite frontend** and a **Spring Boot backend**.
   - The backend owns all business rules, authentication, persistence, and background processing. The frontend is a thin UI that calls the backend over HTTP.

2. **Primary user-facing flows**
   - Employees authenticate, view their account info, inspect pricing records, update prices, and upload pricing files.
   - The app’s core domain is **store pricing data**, plus **audit history** and **file upload processing**.

3. **Backend API boundary**
   - The HTTP layer is organized into three main controllers:
     - **AuthController** for login and current-user/session endpoints.
     - **PricingRecordController** for reading and updating pricing records.
     - **UploadController** for file upload initiation and upload-job status/results.
   - A **GlobalExceptionHandler** centralizes API error translation into consistent responses.

4. **Business logic layer**
   - Services hold the core orchestration:
     - **AuthService** handles login and user/session-related logic.
     - **PricingRecordService** manages pricing retrieval, updates, and audit generation.
     - **UploadService** coordinates file upload lifecycle and job creation.
     - **CsvProcessingService** parses uploaded CSV content and turns it into records/errors.
   - **ActorContext** suggests the backend tracks the current authenticated actor for auditing or business decisions.

5. **Persistence model**
   - The app uses a relational database accessed through Spring Data repositories.
   - Key persisted entities are:
     - **AppUser** and **UserRole** for user access.
     - **PricingRecord** for store price data.
     - **PricingAuditLog** for change history.
     - **UploadedFile**, **UploadJob**, **UploadJobError**, and **UploadJobStatus** for upload tracking.
   - Repositories are dedicated per aggregate, which keeps data access separated from controller/service logic.

6. **Authentication and authorization boundary**
   - Security is JWT-based.
   - **JwtAuthenticationFilter** authenticates requests by reading tokens.
   - **JwtService** issues/validates tokens.
   - **SecurityConfig** wires the security rules, and **JsonAuthenticationEntryPoint** ensures unauthorized responses are returned in API-friendly JSON.
   - **AuthenticatedUser** is the security principal used by the application.

7. **Async processing path for file uploads**
   - Uploads are not just stored; they appear to be processed as a **background job**.
   - The backend has a Kafka-based messaging subsystem:
     - **UploadJobProducer** publishes work.
     - **UploadJobConsumer** consumes and processes upload jobs.
     - **UploadJobMessage** is the payload contract.
   - This creates a clear split between synchronous API handling and asynchronous CSV import execution.

8. **Data and audit flows**
   - The pricing update path likely goes: authenticated user → API → pricing service → database update → audit log entry.
   - The upload path likely goes: user uploads file → backend stores file/job metadata → job message is published → consumer parses CSV → valid rows become pricing updates → invalid rows are stored as job errors.
   - The existence of audit and error entities indicates the system is built for traceability, not just raw data mutation.

9. **Schema management**
   - Database structure is managed with **Flyway** migrations under `src/main/resources/db/migration`.
   - Migrations show the domain evolved in stages:
     - base pricing schema,
     - indexes,
     - user authentication,
     - uploaded file support,
     - later schema refinement.
   - This means the database is treated as a first-class part of the architecture.

10. **Frontend role**
   - The frontend is a separate TypeScript SPA built with **Vite**.
   - `api.ts` is the main integration point to the backend API.
   - `App.tsx` and `main.tsx` wire the UI shell; the built `dist/` output is present in the repo, but the architectural source is the `src/` tree.
   - The frontend does not appear to own business logic; it consumes backend endpoints.

11. **Contracts and integration surface**
   - `openapi-mvp.yaml` suggests an explicit API contract exists for the backend, which is useful for aligning frontend/backend integration and documenting the exposed endpoints.
   - Response/request DTOs in `api/request` and `api/response` isolate the public API from persistence entities.

12. **Infrastructure assumptions visible from the repo**
   - The system depends on at least three infrastructure pieces: a relational database, JWT auth, and Kafka.
   - Those external services are central to the architecture because they separate concerns into:
     - request/response API handling,
     - secure user identity,
     - durable persistence,
     - asynchronous bulk import processing.

Main entry points: [`frontend/src/api.ts`](https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/api.ts) (API Client), [`backend/src/main/java/com/pricingfeed/api/GlobalExceptionHandler.java`](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/GlobalExceptionHandler.java) (Errors), [`backend/src/main/resources/db/migration/V1__mvp_schema.sql`](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/resources/db/migration/V1__mvp_schema.sql) (Migrations), [`backend/src/main/java/com/pricingfeed/service/AuthService.java`](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/AuthService.java) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["UI Shell<br/>React SPA<br/>[App.tsx]"]
  node_frontend_api["API Client<br/>HTTP client<br/>[api.ts]"]
  node_frontend_main["Bootstrap<br/>Vite entry<br/>[main.tsx]"]
end

subgraph group_backend["Backend"]
  node_auth_controller["Auth API<br/>REST controller"]
  node_pricing_controller["Pricing API<br/>REST controller"]
  node_upload_controller["Upload API<br/>REST controller"]
  node_exception_handler["Errors<br/>API advice"]
  node_auth_service["Auth Service<br/>[AuthService.java]"]
  node_pricing_service["Pricing Service"]
  node_upload_service["Upload Service<br/>[UploadService.java]"]
  node_csv_service["CSV Parser"]
  node_actor_context(("Actor Context<br/>[ActorContext.java]"))
  node_jwt_security["JWT Security<br/>[JwtService.java]"]
  node_security_config["Security Config"]
  node_db_pricing[("Pricing Data<br/>entities/repo<br/>[PricingRecord.java]")]
  node_db_users[("Users<br/>entities/repo<br/>[AppUser.java]")]
  node_db_uploads[("Uploads<br/>entities/repo<br/>[UploadJob.java]")]
  node_upload_messaging["Upload Jobs<br/>Kafka messaging"]
end

subgraph group_infra["Infrastructure"]
  node_flyway["Migrations<br/>schema evolution<br/>[V1__mvp_schema.sql]"]
  node_openapi["API Contract<br/>OpenAPI spec<br/>[openapi-mvp.yaml]"]
end

node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -.->|"aligned with"| node_openapi
node_frontend_api -->|"HTTP"| node_auth_controller
node_frontend_api -->|"HTTP"| node_pricing_controller
node_frontend_api -->|"HTTP"| node_upload_controller
node_auth_controller -->|"delegates"| node_auth_service
node_pricing_controller -->|"delegates"| node_pricing_service
node_upload_controller -->|"delegates"| node_upload_service
node_exception_handler -.->|"covers"| node_auth_controller
node_exception_handler -.->|"covers"| node_pricing_controller
node_exception_handler -.->|"covers"| node_upload_controller
node_auth_service -->|"issues tokens"| node_jwt_security
node_jwt_security -->|"wired by"| node_security_config
node_jwt_security -->|"sets actor"| node_actor_context
node_auth_service -->|"reads/writes"| node_db_users
node_pricing_service -->|"reads/writes"| node_db_pricing
node_pricing_service -->|"uses"| node_actor_context
node_upload_service -->|"creates jobs"| node_db_uploads
node_upload_service -->|"publishes"| node_upload_messaging
node_upload_messaging -->|"consumes into"| node_csv_service
node_csv_service -->|"updates"| node_db_pricing
node_csv_service -->|"records errors"| node_db_uploads
node_flyway -.->|"migrates"| node_db_pricing
node_flyway -.->|"migrates"| node_db_users
node_flyway -.->|"migrates"| node_db_uploads

click node_frontend_app "https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/api.ts"
click node_frontend_main "https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/main.tsx"
click node_auth_controller "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/AuthController.java"
click node_pricing_controller "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/PricingRecordController.java"
click node_upload_controller "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/UploadController.java"
click node_exception_handler "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/GlobalExceptionHandler.java"
click node_auth_service "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/AuthService.java"
click node_pricing_service "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/PricingRecordService.java"
click node_upload_service "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/UploadService.java"
click node_csv_service "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/CsvProcessingService.java"
click node_actor_context "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/ActorContext.java"
click node_jwt_security "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/security/JwtService.java"
click node_security_config "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/config/SecurityConfig.java"
click node_db_pricing "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/entity/PricingRecord.java"
click node_db_users "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/entity/AppUser.java"
click node_db_uploads "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/entity/UploadJob.java"
click node_upload_messaging "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/messaging/UploadJobProducer.java"
click node_flyway "https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/resources/db/migration/V1__mvp_schema.sql"
click node_openapi "https://github.com/prasadclasher/pricing-app/blob/main/openapi-mvp.yaml"

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_api,node_frontend_main toneBlue
class node_auth_controller,node_pricing_controller,node_upload_controller,node_exception_handler,node_auth_service,node_pricing_service,node_upload_service,node_csv_service,node_actor_context,node_jwt_security,node_security_config,node_db_pricing,node_db_users,node_db_uploads,node_upload_messaging toneAmber
class node_flyway,node_openapi toneMint
```

## Components

### Frontend

React/Vite single-page app and browser-side API integration

- [UI Shell](https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/App.tsx): React SPA · Main browser application shell and routing/bootstrap entrypoints. · `frontend/src/App.tsx`
- [API Client](https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/api.ts): HTTP client · Frontend integration point for calling backend endpoints. · `frontend/src/api.ts`
- [Bootstrap](https://github.com/prasadclasher/pricing-app/blob/main/frontend/src/main.tsx): Vite entry · Application startup and mounting logic. · `frontend/src/main.tsx`

### Backend

Spring Boot API, business logic, security, persistence, and messaging

- [Auth API](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/AuthController.java): REST controller · Login and current-user/session endpoints. · `backend/src/main/java/com/pricingfeed/api/AuthController.java`
- [Pricing API](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/PricingRecordController.java): REST controller · Read and update pricing records and expose audit views. · `backend/src/main/java/com/pricingfeed/api/PricingRecordController.java`
- [Upload API](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/UploadController.java): REST controller · File upload initiation and job status/result endpoints. · `backend/src/main/java/com/pricingfeed/api/UploadController.java`
- [Errors](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/api/GlobalExceptionHandler.java): API advice · Maps application exceptions to consistent HTTP responses. · `backend/src/main/java/com/pricingfeed/api/GlobalExceptionHandler.java`
- [Auth Service](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/AuthService.java): service · Login and user/session orchestration. · `backend/src/main/java/com/pricingfeed/service/AuthService.java`
- [Pricing Service](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/PricingRecordService.java): service · Pricing retrieval, updates, and audit generation. · `backend/src/main/java/com/pricingfeed/service/PricingRecordService.java`
- [Upload Service](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/UploadService.java): service · Upload lifecycle coordination and job creation. · `backend/src/main/java/com/pricingfeed/service/UploadService.java`
- [CSV Parser](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/CsvProcessingService.java): service · Parses uploaded CSV content into rows and errors. · `backend/src/main/java/com/pricingfeed/service/CsvProcessingService.java`
- [Actor Context](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/service/ActorContext.java): context · Tracks the current authenticated actor for business and audit decisions. · `backend/src/main/java/com/pricingfeed/service/ActorContext.java`
- [JWT Security](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/security/JwtService.java): security · Token issuance, request filtering, entry point, and security rules. · `backend/src/main/java/com/pricingfeed/security/JwtService.java`
- [Security Config](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/config/SecurityConfig.java): config · Wires authentication and authorization rules. · `backend/src/main/java/com/pricingfeed/config/SecurityConfig.java`
- [Pricing Data](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/entity/PricingRecord.java): entities/repo · Pricing records and audit history persisted in the relational database. · `backend/src/main/java/com/pricingfeed/entity/PricingRecord.java`
- [Users](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/entity/AppUser.java): entities/repo · Application users, roles, and user repository boundary. · `backend/src/main/java/com/pricingfeed/entity/AppUser.java`
- [Uploads](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/entity/UploadJob.java): entities/repo · Uploaded files, jobs, statuses, and error rows. · `backend/src/main/java/com/pricingfeed/entity/UploadJob.java`
- [Upload Jobs](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/java/com/pricingfeed/messaging/UploadJobProducer.java): Kafka messaging · Producer/consumer workflow for asynchronous CSV import processing. · `backend/src/main/java/com/pricingfeed/messaging/UploadJobProducer.java`

### Infrastructure

External services and schema management

- [Migrations](https://github.com/prasadclasher/pricing-app/blob/main/backend/src/main/resources/db/migration/V1__mvp_schema.sql): schema evolution · Database schema migrations for pricing, auth, uploads, and refinements. · `backend/src/main/resources/db/migration/V1__mvp_schema.sql`
- [API Contract](https://github.com/prasadclasher/pricing-app/blob/main/openapi-mvp.yaml): OpenAPI spec · Shared API contract for backend endpoints and DTOs. · `openapi-mvp.yaml`

## Connections

- Bootstrap → UI Shell: mounts · Bootstraps the SPA shell.
- UI Shell → API Client: calls · Uses the shared API client for backend requests.
- API Client → API Contract: aligned with · Frontend integration follows the published contract.
- API Client → Auth API: HTTP · Sends login and session requests.
- API Client → Pricing API: HTTP · Reads and updates pricing data.
- API Client → Upload API: HTTP · Starts uploads and polls job status.
- Auth API → Auth Service: delegates · Controller layer hands off auth logic.
- Pricing API → Pricing Service: delegates · Controller layer hands off pricing logic.
- Upload API → Upload Service: delegates · Controller layer hands off upload orchestration.
- Errors → Auth API: covers · Translates errors from API endpoints.
- Errors → Pricing API: covers · Translates errors from API endpoints.
- Errors → Upload API: covers · Translates errors from API endpoints.
- Auth Service → JWT Security: issues tokens · Auth service relies on JWT token creation and validation.
- JWT Security → Security Config: wired by · Security config installs JWT filter and auth rules.
- JWT Security → Actor Context: sets actor · Authenticated principal becomes the current actor.
- Auth Service → Users: reads/writes · Validates and loads user accounts and roles.
- Pricing Service → Pricing Data: reads/writes · Persists pricing records and audit history.
- Pricing Service → Actor Context: uses · Captures who performed the pricing change.
- Upload Service → Uploads: creates jobs · Stores upload files, jobs, and results.
- Upload Service → Upload Jobs: publishes · Enqueues asynchronous import work.
- Upload Jobs → CSV Parser: consumes into · Background consumer parses and processes CSV payloads.
- CSV Parser → Pricing Data: updates · Valid rows become pricing changes.
- CSV Parser → Uploads: records errors · Invalid rows are stored as job errors.
- Migrations → Pricing Data: migrates · Defines pricing and audit schema.
- Migrations → Users: migrates · Defines authentication-related tables and roles.
- Migrations → Uploads: migrates · Defines upload tracking tables and refinements.
