# adittyyaa/ticketing_sys_pv architecture

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

- Interactive diagram: https://gitdiagram.com/adittyyaa/ticketing_sys_pv
- Repository: https://github.com/adittyyaa/ticketing_sys_pv

## Overview

#### Purpose and deployment shape
PV Advisory is a customer-support ticketing system split into a Next.js frontend and a Node.js API backend. Development entry points are the root scripts in `package.json`; service runtimes are `frontend/package.json` (port 3000) and `backend/server.js` (port 3001). Docker support exists in `frontend/Dockerfile` and `backend/Dockerfile`.

#### Frontend application shell and routing
The frontend uses Next.js App Router. Global composition begins in `frontend/src/app/layout.tsx`, with the primary landing surface at `frontend/src/app/page.tsx`. Auth, ticket inbox/detail/create, solutions, and administration are route-level boundaries:
- `frontend/src/app/auth/page.tsx`
- `frontend/src/app/tickets/page.tsx`
- `frontend/src/app/tickets/[id]/page.tsx`
- `frontend/src/app/admin/overview/page.tsx`

Authenticated UI is organized around reusable shell components in `frontend/src/components/layout/AppShell.tsx`, `frontend/src/components/layout/Sidebar.tsx`, and `frontend/src/components/layout/TopBar.tsx`.

#### Client state, session lifecycle, and API boundary
Frontend services isolate HTTP access to the backend: `frontend/src/services/api.ts`, `frontend/src/services/authService.ts`, and `frontend/src/services/ticketService.ts`. Auth initialization and inactivity logout are provider-level concerns in `frontend/src/components/providers/AuthInitProvider.tsx` and `frontend/src/components/providers/InactivityLogoutProvider.tsx`, with consumer hooks in `frontend/src/hooks/useAuth.ts`.

Control flow is UI route/component → feature service/API client → backend REST route. Theme and local UI persistence remain client-side through `frontend/src/contexts/ThemeContext.tsx` and `frontend/src/hooks/useLocalStorage.ts`.

#### Ticketing and knowledge-management UI
Tickets are the dominant workflow: browse/filter via `frontend/src/components/features/tickets/TicketInboxView.tsx` and `frontend/src/components/features/tickets/TicketFilterDrawer.tsx`; inspect ticket records through `frontend/src/components/features/tickets/CommentsSection.tsx` and `frontend/src/components/features/tickets/AttachmentsSection.tsx`. The separate solutions area is exposed at `frontend/src/app/solutions/page.tsx` and calls `frontend/src/services/solutionService.ts`. Feedback is a parallel user-facing workflow through `frontend/src/services/feedbackService.ts` and `frontend/src/components/modals/FeedbackModal.tsx`.

#### Backend HTTP pipeline
`backend/server.js` is the API process entry point. It composes route registration from `backend/routes/index.js`, which partitions the REST surface into auth, tickets, solutions, feedback, and administration:
- `backend/routes/auth.js`
- `backend/routes/tickets.js`
- `backend/routes/admin.js`

Cross-cutting request boundaries are middleware for authentication, validation, security/CORS, logging, and failure handling: `backend/middleware/auth.js`, `backend/middleware/validation.js`, and `backend/middleware/errorHandler.js`. Thus the expected flow is request → middleware → route/controller → service → model/database → response.

#### Backend domain and persistence layers
Controllers adapt HTTP operations into domain services, notably `backend/controllers/ticketController.js`, `backend/controllers/authController.js`, and `backend/controllers/solutionController.js`. Services centralize ticket, comment, authentication, user, feedback, and solution operations in `backend/services/ticketService.js`, `backend/services/commentService.js`, and `backend/services/authService.js`.

Persistence is PostgreSQL-backed per the project documentation. Connection/configuration boundaries are `backend/config/database.js` and `backend/lib/database.js`. Core relational/domain records include `backend/models/Ticket.js`, `backend/models/User.js`, `backend/models/Comment.js`, plus attachments, categories, tags, ticket types, custom statuses, feedback, and solutions.

#### Operations and infrastructure
The system expects PostgreSQL and optionally PgAdmin alongside the two application services. Database bootstrap and production/schema operations are represented by `backend/scripts/setup-production-db.js`, `backend/scripts/verify-schema.js`, and `backend/utils/database-setup-postgresql.sql`. Backend performance work includes SQL changes in `backend/performance-fixes.sql`, monitoring in `backend/performance-monitor.js`, and caching infrastructure in `backend/utils/cache.js`.

Main entry points: [`frontend/src/app/tickets/page.tsx`](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/tickets/page.tsx) (Auth, ticket and admin routes), [`frontend/src/services/api.ts`](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/services/api.ts) (API client and feature services), [`backend/services/ticketService.js`](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/services/ticketService.js) (Ticketing domain services), [`frontend/src/app/layout.tsx`](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/layout.tsx) (App entry and landing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_web_entry["App entry and landing<br/>Next.js App Router<br/>[layout.tsx]"]
  node_route_surfaces["Auth, ticket and admin routes<br/>route pages<br/>[page.tsx]"]
  node_app_shell["Authenticated app shell<br/>layout components<br/>[AppShell.tsx]"]
  node_session_providers["Session lifecycle<br/>auth providers"]
  node_client_api["API client and feature services<br/>HTTP service layer<br/>[api.ts]"]
  node_ticket_ui["Ticket inbox and detail UI<br/>ticket components"]
  node_solutions_ui["Solutions and feedback UI<br/>knowledge UI<br/>[page.tsx]"]
  node_frontend_container["Frontend container<br/>Docker image"]
end

subgraph group_backend["Node.js API"]
  node_api_process["API process<br/>Express server<br/>[server.js]"]
  node_route_registry["REST route registry<br/>route composition<br/>[index.js]"]
  node_request_middleware["Request middleware<br/>cross-cutting pipeline<br/>[auth.js]"]
  node_controllers["HTTP controllers<br/>controller layer"]
  node_domain_services["Ticketing domain services<br/>service layer<br/>[ticketService.js]"]
  node_domain_models["Relational domain models<br/>model layer<br/>[Ticket.js]"]
  node_backend_container["Backend container<br/>Docker image"]
end

subgraph group_data["Data and operations"]
  node_db_access["Database access<br/>PostgreSQL connection layer<br/>[database.js]"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_cache["Cache infrastructure<br/>cache utility<br/>[cache.js]"]
  node_db_bootstrap["Schema bootstrap and verification<br/>database operations"]
  node_performance_ops["Performance monitoring<br/>operations tooling"]
end

node_web_entry -->|"renders routes"| node_route_surfaces
node_route_surfaces -->|"uses"| node_app_shell
node_web_entry -->|"initializes"| node_session_providers
node_route_surfaces -->|"hosts ticket workflow"| node_ticket_ui
node_route_surfaces -->|"hosts knowledge workflow"| node_solutions_ui
node_ticket_ui -->|"calls"| node_client_api
node_solutions_ui -->|"calls"| node_client_api
node_session_providers -->|"manages session through"| node_client_api
node_client_api -->|"REST requests"| node_api_process
node_api_process -->|"registers"| node_route_registry
node_route_registry -->|"passes through"| node_request_middleware
node_request_middleware -->|"authorizes and validates"| node_controllers
node_controllers -->|"invokes"| node_domain_services
node_domain_services -->|"uses"| node_domain_models
node_domain_models -->|"persists through"| node_db_access
node_db_access -->|"connects to"| node_postgres
node_domain_services -.->|"uses"| node_cache
node_db_bootstrap -->|"initializes and verifies"| node_postgres
node_performance_ops -.->|"monitors and tunes"| node_postgres
node_frontend_container -.->|"packages"| node_web_entry
node_backend_container -.->|"packages"| node_api_process

click node_web_entry "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/layout.tsx"
click node_route_surfaces "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/tickets/page.tsx"
click node_app_shell "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/components/layout/AppShell.tsx"
click node_session_providers "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/components/providers/AuthInitProvider.tsx"
click node_client_api "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/services/api.ts"
click node_ticket_ui "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/components/features/tickets/TicketInboxView.tsx"
click node_solutions_ui "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/solutions/page.tsx"
click node_api_process "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/server.js"
click node_route_registry "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/routes/index.js"
click node_request_middleware "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/middleware/auth.js"
click node_controllers "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/controllers/ticketController.js"
click node_domain_services "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/services/ticketService.js"
click node_domain_models "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/models/Ticket.js"
click node_db_access "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/config/database.js"
click node_cache "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/utils/cache.js"
click node_db_bootstrap "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/scripts/setup-production-db.js"
click node_performance_ops "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/performance-monitor.js"
click node_frontend_container "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/Dockerfile"
click node_backend_container "https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/Dockerfile"

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_entry,node_route_surfaces,node_app_shell,node_session_providers,node_client_api,node_ticket_ui,node_solutions_ui,node_frontend_container toneBlue
class node_api_process,node_route_registry,node_request_middleware,node_controllers,node_domain_services,node_domain_models,node_backend_container toneAmber
class node_db_access,node_postgres,node_cache,node_db_bootstrap,node_performance_ops toneMint
```

## Components

### Next.js frontend

- [App entry and landing](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/layout.tsx): Next.js App Router · `frontend/src/app/layout.tsx`
- [Auth, ticket and admin routes](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/tickets/page.tsx): route pages · Route-level boundaries for authentication, ticket workflows, and administration. · `frontend/src/app/tickets/page.tsx`
- [Authenticated app shell](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/components/layout/AppShell.tsx): layout components · `frontend/src/components/layout/AppShell.tsx`
- [Session lifecycle](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/components/providers/AuthInitProvider.tsx): auth providers · Initializes authentication and enforces inactivity logout. · `frontend/src/components/providers/AuthInitProvider.tsx`
- [API client and feature services](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/services/api.ts): HTTP service layer · Isolates backend access for auth, tickets, solutions, and feedback. · `frontend/src/services/api.ts`
- [Ticket inbox and detail UI](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/components/features/tickets/TicketInboxView.tsx): ticket components · Supports filtering, comments, and attachments. · `frontend/src/components/features/tickets/TicketInboxView.tsx`
- [Solutions and feedback UI](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/src/app/solutions/page.tsx): knowledge UI · `frontend/src/app/solutions/page.tsx`
- [Frontend container](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/frontend/Dockerfile): Docker image · `frontend/Dockerfile`

### Node.js API

- [API process](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/server.js): Express server · `backend/server.js`
- [REST route registry](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/routes/index.js): route composition · Partitions auth, tickets, solutions, feedback, and administration endpoints. · `backend/routes/index.js`
- [Request middleware](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/middleware/auth.js): cross-cutting pipeline · Applies authentication, validation, security, logging, and error handling. · `backend/middleware/auth.js`
- [HTTP controllers](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/controllers/ticketController.js): controller layer · Adapts REST operations into domain service calls. · `backend/controllers/ticketController.js`
- [Ticketing domain services](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/services/ticketService.js): service layer · Centralizes ticket, comment, authentication, user, feedback, and solution operations. · `backend/services/ticketService.js`
- [Relational domain models](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/models/Ticket.js): model layer · Includes tickets, users, comments, attachments, taxonomy, feedback, and solutions. · `backend/models/Ticket.js`
- [Backend container](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/Dockerfile): Docker image · `backend/Dockerfile`

### Data and operations

- [Database access](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/config/database.js): PostgreSQL connection layer · `backend/config/database.js`
- **PostgreSQL**: relational database
- [Cache infrastructure](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/utils/cache.js): cache utility · `backend/utils/cache.js`
- [Schema bootstrap and verification](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/scripts/setup-production-db.js): database operations · Supports production setup and schema verification. · `backend/scripts/setup-production-db.js`
- [Performance monitoring](https://github.com/adittyyaa/ticketing_sys_pv/blob/main/backend/performance-monitor.js): operations tooling · Pairs SQL performance fixes with runtime monitoring. · `backend/performance-monitor.js`

## Connections

- App entry and landing → Auth, ticket and admin routes: renders routes
- Auth, ticket and admin routes → Authenticated app shell: uses
- App entry and landing → Session lifecycle: initializes
- Auth, ticket and admin routes → Ticket inbox and detail UI: hosts ticket workflow
- Auth, ticket and admin routes → Solutions and feedback UI: hosts knowledge workflow
- Ticket inbox and detail UI → API client and feature services: calls
- Solutions and feedback UI → API client and feature services: calls
- Session lifecycle → API client and feature services: manages session through
- API client and feature services → API process: REST requests
- API process → REST route registry: registers
- REST route registry → Request middleware: passes through
- Request middleware → HTTP controllers: authorizes and validates
- HTTP controllers → Ticketing domain services: invokes
- Ticketing domain services → Relational domain models: uses
- Relational domain models → Database access: persists through
- Database access → PostgreSQL: connects to
- Ticketing domain services → Cache infrastructure: uses
- Schema bootstrap and verification → PostgreSQL: initializes and verifies
- Performance monitoring → PostgreSQL: monitors and tunes
- Frontend container → App entry and landing: packages
- Backend container → API process: packages