# kalpatarudash2005/xershop architecture

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

- Interactive diagram: https://gitdiagram.com/kalpatarudash2005/xershop
- Repository: https://github.com/kalpatarudash2005/xershop

## Overview

1. **Overall shape**
   - PrintHub is a two-part system: a **Spring Boot backend** and a **Next.js frontend**.
   - The backend acts as the primary application server and API boundary; the web app is the customer/admin UI that consumes those APIs.

2. **Frontend boundary**
   - `printhub-web` is a **Next.js 14 / TypeScript / Tailwind** app using the App Router.
   - It contains public marketing pages plus authenticated flows for **login, register, upload, shops, orders, and an admin dashboard**.
   - `src/lib/api.ts` is the main client-side integration point to the backend, while `src/store/authStore.ts` and `src/middleware.ts` indicate client/session state and route protection.

3. **Backend boundary**
   - `printhub-backend` is a **Spring Boot 3.3 / Java 21** service exposed as REST APIs.
   - Controllers are split by domain: `Auth`, `User`, `Shop`, `Order`, `Payment`, `File`, and `Admin`.
   - The backend is the system of record for users, shops, orders, payments, wallets, reviews, notifications, coupons, and platform settings.

4. **Layered backend architecture**
   - The backend follows a classic layered structure:
     - **Controller**: request/response endpoints.
     - **Service**: business rules and orchestration.
     - **Repository**: persistence access via Spring Data JPA.
     - **Entity**: domain model mapped to the database.
     - **DTO + Mapper**: API contracts separated from persistence entities.
   - This separation is important for diagramming because almost all domain flows pass through this pipeline.

5. **Core domain model**
   - The central business entities are around print-order fulfillment:
     - **User / Shop / Printer / Inventory / Category**
     - **Order / OrderItem / OrderTimeline / OrderStatus**
     - **Payment / Wallet / WalletTransaction**
     - **Coupon / Review / Notification / Referral**
   - Supporting entities like `PlatformSettings`, `PricingRule`, `CmsPage`, and `CmsBanner` suggest the platform includes configurable pricing and content management, not just transactions.

6. **Primary data flows**
   - **Authentication flow**: frontend submits credentials to `AuthController`; backend uses `AuthService`, `JwtService`, `JwtAuthenticationFilter`, and refresh-token persistence.
   - **Order flow**: frontend places or views orders; backend creates and tracks orders, order items, timeline/status changes, and related notifications.
   - **Payment flow**: payment data goes through `PaymentController`/`PaymentService`, with manual verification support reflected in the migrations.
   - **File upload flow**: the web app’s upload page likely sends documents to `FileController`, backed by `FileStorageService` and local filesystem storage.
   - **Admin flow**: admin dashboard actions go to admin-specific endpoints for platform oversight.

7. **Security and identity**
   - Security is JWT-based with **access + refresh tokens** and **BCrypt** password hashing.
   - `SecurityConfig`, `UserDetailsServiceImpl`, and `UserPrincipal` define authenticated identity and authorization.
   - Role boundaries are explicit in the model via `UserRole`, and the readme indicates separate admin and shop-owner accounts.

8. **Persistence and migrations**
   - The backend uses **H2 file-based storage** for local development/runtime, with **Flyway** migrations under `src/main/resources/db/migration`.
   - This means schema and seed data are managed as versioned SQL scripts rather than generated ad hoc.
   - The data layer is therefore stable and reproducible across environments, especially with seeded default users and promo codes.

9. **Storage and non-database state**
   - Uploaded documents are stored in the **local filesystem** (`/app/uploads` per README).
   - That storage is treated as a separate runtime dependency from the database, which matters for deployment diagrams because it likely requires a Docker volume or mounted path.
   - Refresh tokens and other application state are persisted in the database rather than kept only in memory.

10. **Realtime and platform concerns**
   - `WebSocketConfig` shows a realtime channel exists, likely for notifications or order updates.
   - `CacheConfig` indicates in-memory caching for performance-sensitive reads.
   - `OpenApiConfig` means the backend exposes Swagger/OpenAPI documentation, useful as a contract boundary for the frontend and external consumers.

11. **Operational packaging**
   - The repository is containerized: both services have Dockerfiles, and the root `docker-compose.yml` orchestrates the local stack.
   - The backend also includes environment-specific YAML files (`application-dev.yml`, `application-prod.yml`), so runtime behavior changes by deployment target.
   - GitHub Actions workflows in `.github/workflows` suggest CI validation and build/deploy automation.

12. **Testing and quality gates**
   - Backend tests cover repositories, services, and controller integration paths, which implies the domain logic is validated close to the API boundary.
   - The frontend is more route/component driven, with architecture centered on page composition and API consumption.
   - For a diagram, it is useful to show testing as a cross-cutting layer around the backend services and APIs.

13. **External/configurable integrations**
   - The README and configuration notes reference **UPI QR code**, **WhatsApp notifications**, and **Twilio credentials** as environment/configuration items.
   - These are not core infrastructure components in the repo tree, but they are important external touchpoints because they affect payment and notification behavior.

14. **Suggested diagram emphasis**
   - Show two top-level deployables: **Next.js web app** and **Spring Boot API**.
   - Inside the backend, emphasize the path **Controller → Service → Repository → Entity → H2/Flyway**.
   - Draw separate side systems for **JWT auth**, **local file storage**, and **WebSocket notifications**.
   - Keep admin/customer frontend flows distinct, since the repo clearly includes both public marketplace pages and an admin dashboard.

Main entry points: [`printhub-backend/src/main/java/com/printhub/service`](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/service) (Services), [`printhub-backend/src/main/java/com/printhub/controller`](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/controller) (Controllers), [`printhub-web/src/lib/api.ts`](https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/lib/api.ts) (API Client), [`printhub-web`](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web) (PrintHub Web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web App"]
  node_web_app["PrintHub Web<br/>Next.js app"]
  node_web_home["Public Pages<br/>marketing routes"]
  node_web_auth["Auth Flows<br/>session routes"]
  node_web_market["Shop Flow<br/>customer routes"]
  node_web_admin["Admin Dashboard<br/>admin route"]
  node_web_api["API Client<br/>frontend integration<br/>[api.ts]"]
  node_web_store["Auth Store<br/>client state<br/>[authStore.ts]"]
  node_web_mw{{"Route Guard<br/>middleware<br/>[middleware.ts]"}}
end

subgraph group_api["Backend API"]
  node_api_app["PrintHub API<br/>Spring Boot app"]
  node_api_ctrl["Controllers<br/>REST boundary"]
  node_api_svc["Services<br/>business layer"]
  node_api_repo[("Repositories<br/>data access")]
  node_api_entity["Entities<br/>domain model"]
  node_api_dto["DTOs & Mappers<br/>contract layer"]
  node_api_sec{{"JWT Security<br/>security layer"}}
  node_api_cfg["Platform Config<br/>cross-cutting config"]
  node_api_flyway["Flyway Migrations<br/>schema/versioning"]
end

subgraph group_infra["Runtime & Ops"]
  node_infra_db[("H2 Database<br/>local datastore<br/>[application.yml]")]
  node_infra_fs[("Upload Storage<br/>filesystem<br/>[application.yml]")]
  node_infra_ext{{"External Integrations<br/>payment/notification deps<br/>[README.md]"}}
end

node_web_app -->|"hosts"| node_web_home
node_web_app -->|"hosts"| node_web_auth
node_web_app -->|"hosts"| node_web_market
node_web_app -->|"hosts"| node_web_admin
node_web_home -->|"fetches data"| node_web_api
node_web_auth -->|"calls"| node_web_api
node_web_market -->|"calls"| node_web_api
node_web_admin -->|"calls"| node_web_api
node_web_store -->|"supports"| node_web_auth
node_web_mw -->|"protects"| node_web_auth
node_web_mw -->|"protects"| node_web_admin
node_web_api -->|"requests"| node_api_ctrl
node_api_ctrl -->|"delegates"| node_api_svc
node_api_svc -->|"reads/writes"| node_api_repo
node_api_repo -->|"maps"| node_api_entity
node_api_dto -->|"shapes payloads"| node_api_ctrl
node_api_ctrl -->|"returns"| node_api_dto
node_api_sec -->|"guards"| node_api_ctrl
node_api_sec -->|"identifies users"| node_api_svc
node_api_cfg -->|"configures"| node_api_sec
node_api_cfg -->|"exposes"| node_api_ctrl
node_api_svc -->|"persists"| node_infra_db
node_api_flyway -->|"migrates"| node_infra_db
node_api_svc -->|"stores files"| node_infra_fs
node_api_svc -.->|"integrates"| node_infra_ext
node_api_entity -.->|"evolves via"| node_api_flyway

click node_web_app "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web"
click node_web_home "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app"
click node_web_auth "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app/login"
click node_web_market "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app/shops"
click node_web_admin "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app/admin/dashboard"
click node_web_api "https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/lib/api.ts"
click node_web_store "https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/store/authStore.ts"
click node_web_mw "https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/middleware.ts"
click node_api_app "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend"
click node_api_ctrl "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/controller"
click node_api_svc "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/service"
click node_api_repo "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/repository"
click node_api_entity "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/entity"
click node_api_dto "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/dto"
click node_api_sec "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/security"
click node_api_cfg "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/config"
click node_api_flyway "https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/resources/db/migration"
click node_infra_db "https://github.com/kalpatarudash2005/xershop/blob/main/printhub-backend/src/main/resources/application.yml"
click node_infra_fs "https://github.com/kalpatarudash2005/xershop/blob/main/printhub-backend/src/main/resources/application.yml"
click node_infra_ext "https://github.com/kalpatarudash2005/xershop/blob/main/README.md"

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_web_app,node_web_home,node_web_auth,node_web_market,node_web_admin,node_web_api,node_web_store,node_web_mw toneBlue
class node_api_app,node_api_ctrl,node_api_svc,node_api_repo,node_api_entity,node_api_dto,node_api_sec,node_api_cfg,node_api_flyway toneAmber
class node_infra_db,node_infra_fs,node_infra_ext toneMint
```

## Components

### Web App

Next.js frontend and route-level UI flows.

- [PrintHub Web](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web): Next.js app · Customer and admin UI built with Next.js 14, TypeScript, and Tailwind. · `printhub-web`
- [Public Pages](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app): marketing routes · Home, about, FAQ, help, contact, privacy, and terms pages. · `printhub-web/src/app`
- [Auth Flows](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app/login): session routes · Login, register, forgot-password, and route protection for authenticated access. · `printhub-web/src/app/login`
- [Shop Flow](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app/shops): customer routes · Shop browsing, shop details, upload, and order viewing flows. · `printhub-web/src/app/shops`
- [Admin Dashboard](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-web/src/app/admin/dashboard): admin route · Admin-facing dashboard entry point for platform oversight. · `printhub-web/src/app/admin/dashboard`
- [API Client](https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/lib/api.ts): frontend integration · Client-side API layer used by pages and components to call the backend. · `printhub-web/src/lib/api.ts`
- [Auth Store](https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/store/authStore.ts): client state · Client-side auth/session state used by protected UI flows. · `printhub-web/src/store/authStore.ts`
- [Route Guard](https://github.com/kalpatarudash2005/xershop/blob/main/printhub-web/src/middleware.ts): middleware · Middleware that protects authenticated and role-specific routes. · `printhub-web/src/middleware.ts`

### Backend API

Spring Boot service, layered domain logic, and persistence.

- [PrintHub API](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend): Spring Boot app · Primary backend service exposing REST APIs for the platform. · `printhub-backend`
- [Controllers](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/controller): REST boundary · Domain endpoints for auth, users, shops, orders, payments, files, and admin. · `printhub-backend/src/main/java/com/printhub/controller`
- [Services](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/service): business layer · Business rules and orchestration for authentication, orders, payments, shops, users, and admin. · `printhub-backend/src/main/java/com/printhub/service`
- [Repositories](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/repository): data access · Spring Data JPA repositories for domain persistence. · `printhub-backend/src/main/java/com/printhub/repository`
- [Entities](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/entity): domain model · Core domain model for users, shops, orders, payments, wallets, coupons, notifications, and settings. · `printhub-backend/src/main/java/com/printhub/entity`
- [DTOs & Mappers](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/dto): contract layer · API payloads and mapping between entities and transport objects. · `printhub-backend/src/main/java/com/printhub/dto`
- [JWT Security](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/security): security layer · JWT auth, refresh tokens, user details, and request filtering. · `printhub-backend/src/main/java/com/printhub/security`
- [Platform Config](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/java/com/printhub/config): cross-cutting config · Security, cache, OpenAPI, JPA auditing, and WebSocket configuration. · `printhub-backend/src/main/java/com/printhub/config`
- [Flyway Migrations](https://github.com/kalpatarudash2005/xershop/tree/main/printhub-backend/src/main/resources/db/migration): schema/versioning · Versioned SQL migrations and seeded data for schema evolution. · `printhub-backend/src/main/resources/db/migration`

### Runtime & Ops

Shared storage, security, and deployment concerns.

- [H2 Database](https://github.com/kalpatarudash2005/xershop/blob/main/printhub-backend/src/main/resources/application.yml): local datastore · File-based development database and system of record for persisted application state. · `printhub-backend/src/main/resources/application.yml`
- [Upload Storage](https://github.com/kalpatarudash2005/xershop/blob/main/printhub-backend/src/main/resources/application.yml): filesystem · Local filesystem storage for uploaded documents and related files. · `printhub-backend/src/main/resources/application.yml`
- [External Integrations](https://github.com/kalpatarudash2005/xershop/blob/main/README.md): payment/notification deps · Configured touchpoints such as UPI QR, WhatsApp, and Twilio credentials. · `README.md`

## Connections

- PrintHub Web → Public Pages: hosts · The app renders public marketing and informational pages.
- PrintHub Web → Auth Flows: hosts · The app provides authentication and account access routes.
- PrintHub Web → Shop Flow: hosts · The app provides marketplace and order-centric customer flows.
- PrintHub Web → Admin Dashboard: hosts · The app exposes an admin dashboard route.
- Public Pages → API Client: fetches data · Public pages can consume backend data through the shared API client.
- Auth Flows → API Client: calls · Login and registration flows submit requests through the API client.
- Shop Flow → API Client: calls · Shop, upload, and order pages integrate with backend APIs.
- Admin Dashboard → API Client: calls · Admin actions are sent to backend admin endpoints.
- Auth Store → Auth Flows: supports · Client auth state feeds protected UI behavior.
- Route Guard → Auth Flows: protects · Middleware guards authenticated and role-based routes.
- Route Guard → Admin Dashboard: protects · Middleware helps restrict the admin dashboard.
- API Client → Controllers: requests · The frontend talks to the backend through REST controllers.
- Controllers → Services: delegates · Controllers hand off business work to services.
- Services → Repositories: reads/writes · Services persist and query data through repositories.
- Repositories → Entities: maps · Repositories operate on JPA entities.
- DTOs & Mappers → Controllers: shapes payloads · DTOs define request and response contracts at the API boundary.
- Controllers → DTOs & Mappers: returns · Controllers serialize DTOs back to clients.
- JWT Security → Controllers: guards · Security filters sit in front of request handling.
- JWT Security → Services: identifies users · Authenticated identity is resolved for service-level authorization.
- Platform Config → JWT Security: configures · Security configuration wires JWT-based authentication.
- Platform Config → Controllers: exposes · OpenAPI and WebSocket infrastructure support the API layer.
- Services → H2 Database: persists · Core application state is stored in the H2 database.
- Flyway Migrations → H2 Database: migrates · Versioned SQL migrations evolve and seed the database.
- Services → Upload Storage: stores files · File storage service writes uploads to the local filesystem.
- Services → External Integrations: integrates · Payments and notifications can depend on external configured services.
- Entities → Flyway Migrations: evolves via · Entities are reflected in schema changes managed by migrations.
