How kalpatarudash2005/xershop works
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: service Services · controller Controllers · api.ts API Client · printhub-web PrintHub Web
Components 20
Web App
Next.js frontend and route-level UI flows.
- PrintHub Web · Customer and admin UI built with Next.js 14, TypeScript, and Tailwind.
printhub-web - Public Pages · Home, about, FAQ, help, contact, privacy, and terms pages.
printhub-web/src/app - Auth Flows · Login, register, forgot-password, and route protection for authenticated access.
printhub-web/src/app/login - Shop Flow · Shop browsing, shop details, upload, and order viewing flows.
printhub-web/src/app/shops - Admin Dashboard · Admin-facing dashboard entry point for platform oversight.
printhub-web/src/app/admin/dashboard - API Client · Client-side API layer used by pages and components to call the backend.
printhub-web/src/lib/api.ts - Auth Store · Client-side auth/session state used by protected UI flows.
printhub-web/src/store/authStore.ts - Route Guard · 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 · Primary backend service exposing REST APIs for the platform.
printhub-backend - Controllers · Domain endpoints for auth, users, shops, orders, payments, files, and admin.
printhub-backend/src/main/java/com/printhub/controller - Services · Business rules and orchestration for authentication, orders, payments, shops, users, and admin.
printhub-backend/src/main/java/com/printhub/service - Repositories · Spring Data JPA repositories for domain persistence.
printhub-backend/src/main/java/com/printhub/repository - Entities · Core domain model for users, shops, orders, payments, wallets, coupons, notifications, and settings.
printhub-backend/src/main/java/com/printhub/entity - DTOs & Mappers · API payloads and mapping between entities and transport objects.
printhub-backend/src/main/java/com/printhub/dto - JWT Security · JWT auth, refresh tokens, user details, and request filtering.
printhub-backend/src/main/java/com/printhub/security - Platform Config · Security, cache, OpenAPI, JPA auditing, and WebSocket configuration.
printhub-backend/src/main/java/com/printhub/config - Flyway Migrations · 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 · File-based development database and system of record for persisted application state.
printhub-backend/src/main/resources/application.yml - Upload Storage · Local filesystem storage for uploaded documents and related files.
printhub-backend/src/main/resources/application.yml - External Integrations · Configured touchpoints such as UPI QR, WhatsApp, and Twilio credentials.
README.md
Connections 26
- 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.