How amanchauhan-dev/invoice-harmony works
1. This repository is a split frontend/backend application for a business workflow centered on customers, invoices, payments, dashboards, and settings. The two halves communicate over an HTTP API, with the frontend acting as the presentation and session layer and the backend as the domain/API and persistence layer.
2. The backend is organized as a feature-modular TypeScript server under backend/src/features. Each feature has the same three-part shape: *.routes.ts for endpoint wiring, *.controller.ts for request/response handling, and *.service.ts for business logic. The main feature boundaries are auth, customer, dashboard, invoice, payment, profile, settings, and health.
3. backend/src/app.ts and backend/src/index.ts form the server bootstrap path. Cross-cutting middleware lives in backend/src/middlewares, including auth.middleware.ts for protecting private endpoints and errorHandler.ts for centralized error translation. This means request flow is: route -> controller -> service -> middleware/error handler.
4. Persistence is isolated behind Prisma. backend/prisma/schema.prisma defines the data model, backend/src/lib/prisma.ts provides the Prisma client, and backend/prisma.config.ts supports Prisma setup. The backend services are the only layer that should talk to the database directly, which keeps controllers thin and makes the data access boundary explicit.
5. Shared request validation lives in backend/src/shared/zod-schemas.ts. That implies input shape checking is standardized across features, likely before business logic runs. For architecture purposes, validation sits between route/controller entry and service execution, reducing invalid-data leakage into the domain layer.
6. The auth feature is the main security boundary on the backend. It is paired with the auth middleware and front-end route protection, so login/session state determines whether the user can access invoice/customer/payment pages or not. This is the main boundary between public and private application areas.
7. The frontend is a Vite + React + TypeScript SPA. frontend/src/main.tsx boots the app, App.tsx defines top-level routing/layout, and frontend/src/pages contains page-level views for Auth, Dashboard, Customers, Invoices, CreateInvoice, ViewInvoice, PayInvoice, Payments, Reports, Settings, Index, and NotFound.
8. Frontend navigation is split into public and protected areas. frontend/src/components/ProtectedRoute.tsx gates authenticated routes, while frontend/src/context/AuthContext.tsx and frontend/src/hooks/use-auth.ts hold session/auth state for the UI. frontend/src/components/layout/AppLayout.tsx and AppSidebar.tsx define the authenticated shell used by the app’s internal pages.
9. API access on the frontend is centralized in frontend/src/services/api.service.ts. That service is the main outbound data-flow boundary from the SPA to the backend. Pages likely call this layer rather than fetching directly, which keeps network concerns separate from rendering logic.
10. The UI is built from a reusable component library under frontend/src/components/ui, plus app-specific wrappers such as ThemeProvider, NavLink, and the layout components. This suggests a design-system approach: pages assemble screens from shared primitives rather than duplicating controls.
11. The domain-specific frontend pages map closely to backend features: invoices and payments have both list/detail and action pages, customers have their own management page, dashboard aggregates business data, and reports/settings provide secondary workflows. That close page-to-feature mapping makes the app’s main diagram easy to draw as a set of domain slices over a shared API and auth layer.
12. Tooling supports both UI and server quality gates. The frontend includes Vitest and Playwright configuration for unit and end-to-end testing, and the backend uses TypeScript + Prisma-oriented setup. From an architecture standpoint, tests sit alongside the app code rather than introducing a separate runtime service.
Main entry points: app.ts App config · AppLayout.tsx App layout · prisma.ts Prisma client · App.tsx Router shell
Components 29
Backend API
TypeScript HTTP API, feature modules, middleware, and persistence boundary.
- Server entry · Starts the backend process and hands off to the app setup.
backend/src/index.ts - App config · Wires the server, routes, and shared middleware.
backend/src/app.ts - Auth middleware · Protects private backend endpoints.
backend/src/middlewares/auth.middleware.ts - Error handler · Centralizes API error translation.
backend/src/middlewares/errorHandler.ts - Zod schemas · Shared request validation shapes used across features.
backend/src/shared/zod-schemas.ts - Prisma client · Backend database access entry point.
backend/src/lib/prisma.ts - Data model · Prisma schema defining persistence structure.
backend/prisma/schema.prisma - Auth · Login and session boundary for private access.
backend/src/features/auth/auth.routes.ts - Customers · Customer management APIs.
backend/src/features/customer/customer.routes.ts - Invoices · Invoice creation, lookup, and lifecycle APIs.
backend/src/features/invoice/invoice.routes.ts - Payments · Payment-related API workflows.
backend/src/features/payment/payment.routes.ts - Dashboard · Aggregated business metrics and summaries.
backend/src/features/dashboard/dashboard.routes.ts - Profile · Current-user profile APIs.
backend/src/features/profile/profile.routes.ts - Settings · Application settings APIs.
backend/src/features/settings/settings.routes.ts - Health · Service liveness and readiness endpoint.
backend/src/features/health/health.routes.ts
Frontend SPA
React application shell, auth/session state, pages, and shared UI.
- App entry · Bootstraps the React application.
frontend/src/main.tsx - Router shell · Defines top-level routing and layout composition.
frontend/src/App.tsx - Auth state · Holds session and auth state for the UI.
frontend/src/context/AuthContext.tsx - Protected route · Blocks unauthenticated access to private pages.
frontend/src/components/ProtectedRoute.tsx - App layout · Authenticated application frame for private screens.
frontend/src/components/layout/AppLayout.tsx - Sidebar · Primary navigation for the authenticated shell.
frontend/src/components/layout/AppSidebar.tsx - API service · Centralized frontend access to the backend API.
frontend/src/services/api.service.ts - Auth page · Public sign-in and access flow.
frontend/src/pages/Auth.tsx - Dashboard page · Business overview and metrics screen.
frontend/src/pages/Dashboard.tsx - Customers page · Customer management screen.
frontend/src/pages/Customers.tsx - Invoices pages · Invoice list, create, and view workflows.
frontend/src/pages/Invoices.tsx - Payments page · Payment history and payment workflows.
frontend/src/pages/Payments.tsx - Settings page · Settings and secondary account workflows.
frontend/src/pages/Settings.tsx - Reports page · Reporting and analytics views.
frontend/src/pages/Reports.tsx
Connections 47
- Server entry → App config: bootstraps · Process entry starts the server configuration.
- App config → Auth middleware: uses · Applies auth protection to private API routes.
- App config → Error handler: uses · Registers centralized error handling.
- App config → Auth: mounts · Wires the auth feature routes into the app.
- App config → Customers: mounts · Wires customer APIs.
- App config → Invoices: mounts · Wires invoice APIs.
- App config → Payments: mounts · Wires payment APIs.
- App config → Dashboard: mounts · Wires dashboard APIs.
- App config → Profile: mounts · Wires profile APIs.
- App config → Settings: mounts · Wires settings APIs.
- App config → Health: mounts · Wires health endpoints.
- Auth → Zod schemas: validates · Uses shared request schemas.
- Customers → Zod schemas: validates · Uses shared request schemas.
- Invoices → Zod schemas: validates · Uses shared request schemas.
- Payments → Zod schemas: validates · Uses shared request schemas.
- Dashboard → Zod schemas: validates · Uses shared request schemas.
- Profile → Zod schemas: validates · Uses shared request schemas.
- Settings → Zod schemas: validates · Uses shared request schemas.
- Auth → Prisma client: persists via · Feature services access the database through Prisma.
- Customers → Prisma client: persists via · Feature services access the database through Prisma.
- Invoices → Prisma client: persists via · Feature services access the database through Prisma.
- Payments → Prisma client: persists via · Feature services access the database through Prisma.
- Dashboard → Prisma client: reads via · Feature services aggregate data from persistence.
- Profile → Prisma client: persists via · Feature services access the database through Prisma.
- Settings → Prisma client: persists via · Feature services access the database through Prisma.
- Prisma client → Data model: implements · Client is generated from the schema model.
- App entry → Router shell: boots · Entry point renders the app shell.
- Router shell → Auth state: uses · Shares authentication state across the UI.
- Router shell → Protected route: uses · Wraps private routes with access control.
- Router shell → App layout: uses · Composes the authenticated shell.
- App layout → Sidebar: contains · Navigation is part of the app shell.
- Auth page → API service: calls · Public auth workflow reaches the backend through the API service.
- Dashboard page → API service: calls · Dashboard data is fetched through the shared API client.
- Customers page → API service: calls · Customer workflows use the shared API client.
- Invoices pages → API service: calls · Invoice workflows use the shared API client.
- Payments page → API service: calls · Payment workflows use the shared API client.
- Settings page → API service: calls · Settings workflows use the shared API client.
- Reports page → API service: calls · Reports and analytics use the shared API client.
- Protected route → Auth state: checks · Route guard reads session state.
- App layout → Dashboard page: hosts · Authenticated shell renders internal pages.
- App layout → Customers page: hosts · Authenticated shell renders internal pages.
- App layout → Invoices pages: hosts · Authenticated shell renders internal pages.
- App layout → Payments page: hosts · Authenticated shell renders internal pages.
- App layout → Settings page: hosts · Authenticated shell renders internal pages.
- App layout → Reports page: hosts · Authenticated shell renders internal pages.
- Router shell → Auth page: routes to · Public route entry.
- Router shell → Protected route: routes through · Private route entry.