# din-esh-kumar/synergy architecture

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

- Interactive diagram: https://gitdiagram.com/din-esh-kumar/synergy
- Repository: https://github.com/din-esh-kumar/synergy

## Overview

#### Purpose and entry points
This is a full-stack project-management/issue-tracking system with authentication, users, projects, issues, and periodic updates. The backend is a TypeScript HTTP API started through `backend/src/server.ts`, which builds the application in `backend/src/app.ts`. The frontend is a Vite React SPA bootstrapped by `frontend/src/main.tsx`, rooted at `frontend/src/App.tsx`, and routed through `frontend/src/router.tsx`.

#### Frontend application shell and state
The SPA provides application-wide authentication and theme state via `frontend/src/context/AuthContext.tsx` and `frontend/src/context/ThemeContext.tsx`. Feature hooks such as `frontend/src/hooks/useIssues.ts`, `frontend/src/hooks/useProjects.ts`, and `frontend/src/hooks/useUsers.ts` connect UI state to API-backed domain data. Routing is the main frontend control boundary: authenticated views should consume auth context rather than independently managing credentials.

#### API client and feature service boundary
Frontend network access is centralized in `frontend/src/services/api.ts`. Domain-specific services—`frontend/src/services/auth.service.ts`, `frontend/src/services/issue.service.ts`, `frontend/src/services/project.service.ts`, and `frontend/src/services/updates.service.ts`—encapsulate endpoint calls and isolate components/hooks from HTTP details. Shared API/domain contracts are represented by paths including `frontend/src/types/auth.types.ts`, `frontend/src/types/issue.types.ts`, and `frontend/src/types/project.types.ts`.

#### Backend HTTP composition
`backend/src/app.ts` composes middleware and route modules; `backend/src/server.ts` owns process startup. API capability is partitioned by route/controller pairs: authentication (`backend/src/routes/auth.routes.ts`, `backend/src/controllers/auth.controller.ts`), projects (`backend/src/routes/project.routes.ts`, `backend/src/controllers/project.controller.ts`), issues (`backend/src/routes/issue.routes.ts`, `backend/src/controllers/issue.controller.ts`), and updates (`backend/src/routes/updates.routes.ts`, `backend/src/controllers/updates.controller.ts`). Controllers are the request-to-domain/persistence boundary.

#### Authentication, authorization, and request protection
Auth uses JWT support in `backend/src/utils/jwt.ts`, enforced by `backend/src/middleware/auth.middleware.ts`. Role-based access is a separate policy layer in `backend/src/middleware/role.middleware.ts`; input validation and uniform failure handling are provided by `backend/src/middleware/validators.ts` and `backend/src/middleware/errorHandler.ts`. Requests therefore flow from route matching through authentication/authorization/validation into controllers, with errors returning through centralized middleware.

#### Persistence and domain model
The backend has database initialization in `backend/src/config/database.ts` and model definitions under `backend/src/config/`, including `backend/src/config/User.model.ts`, `backend/src/config/Project.model.ts`, `backend/src/config/Issue.model.ts`, plus Task, Team, Settings, AuditLog, DailyUpdate, and WeeklyUpdate models. A parallel `backend/src/models/` set (`backend/src/models/User.model.ts`, `backend/src/models/Project.model.ts`, `backend/src/models/Issue.model.ts`, `backend/src/models/Update.model.ts`) suggests controller-facing domain model imports may be distinct from—or duplicative of—configured persistence schemas; this is an important ownership boundary to resolve before extending data flows.

#### External infrastructure
The system requires a configured backend database connection and environment values in `backend/.env`; frontend runtime endpoint configuration is in `frontend/.env`. `backend/src/utils/s3.ts` indicates an Amazon S3 integration, likely for object/file storage, and should remain behind this utility boundary rather than being called directly from controllers or frontend code.

Main entry points: [`frontend/src/App.tsx`](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/App.tsx) (Application shell), [`frontend/src/services/issue.service.ts`](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/services/issue.service.ts) (Domain API services), [`backend/src/middleware/auth.middleware.ts`](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/middleware/auth.middleware.ts) (Request protection), [`backend/src/controllers/issue.controller.ts`](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/controllers/issue.controller.ts) (Domain controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_fe_main["SPA bootstrap<br/>Vite entry<br/>[main.tsx]"]
  node_fe_app["Application shell<br/>React root<br/>[App.tsx]"]
  node_fe_router["Route boundary<br/>React router<br/>[router.tsx]"]
  node_fe_context["Auth and theme state<br/>React contexts<br/>[AuthContext.tsx]"]
  node_fe_hooks["Domain data hooks<br/>feature hooks<br/>[useIssues.ts]"]
  node_fe_services["Domain API services<br/>service layer<br/>[issue.service.ts]"]
  node_fe_api["HTTP client<br/>API client<br/>[api.ts]"]
  node_fe_contracts["Frontend contracts<br/>TypeScript types<br/>[issue.types.ts]"]
end

subgraph group_backend["HTTP API"]
  node_be_server["API process startup<br/>server entry<br/>[server.ts]"]
  node_be_app["HTTP application<br/>app composition<br/>[app.ts]"]
  node_be_routes["Capability routes<br/>route modules<br/>[auth.routes.ts]"]
  node_be_protection["Request protection<br/>middleware chain<br/>[auth.middleware.ts]"]
  node_be_controllers["Domain controllers"]
  node_be_jwt["JWT utility<br/>token utility<br/>[jwt.ts]"]
  node_s3[("Object storage<br/>S3 integration<br/>[s3.ts]")]
end

subgraph group_data["Persistence"]
  node_db_init[("Database connection<br/>database initialization<br/>[database.ts]")]
  node_db_schemas["Configured schemas<br/>persistence models<br/>[Issue.model.ts]"]
  node_domain_models["Controller-facing models<br/>domain models<br/>[Issue.model.ts]"]
end

node_fe_main -->|"mounts"| node_fe_app
node_fe_app -->|"renders"| node_fe_router
node_fe_app -->|"provides"| node_fe_context
node_fe_router -->|"drives views"| node_fe_hooks
node_fe_hooks -->|"loads and mutates"| node_fe_services
node_fe_services -->|"uses"| node_fe_api
node_fe_services -->|"uses contracts"| node_fe_contracts
node_fe_api -->|"HTTP API"| node_be_app
node_be_server -->|"starts"| node_be_app
node_be_app -->|"mounts"| node_be_routes
node_be_routes -->|"applies"| node_be_protection
node_be_protection -->|"verifies tokens"| node_be_jwt
node_be_protection -->|"authorizes and validates"| node_be_controllers
node_be_controllers -->|"uses"| node_domain_models
node_domain_models -.->|"parallel ownership"| node_db_schemas
node_db_schemas -->|"connects through"| node_db_init
node_be_controllers -->|"file storage"| node_s3

click node_fe_main "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/main.tsx"
click node_fe_app "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/App.tsx"
click node_fe_router "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/router.tsx"
click node_fe_context "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/context/AuthContext.tsx"
click node_fe_hooks "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/hooks/useIssues.ts"
click node_fe_services "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/services/issue.service.ts"
click node_fe_api "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/services/api.ts"
click node_fe_contracts "https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/types/issue.types.ts"
click node_be_server "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/server.ts"
click node_be_app "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/app.ts"
click node_be_routes "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/routes/auth.routes.ts"
click node_be_protection "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/middleware/auth.middleware.ts"
click node_be_controllers "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/controllers/issue.controller.ts"
click node_be_jwt "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/utils/jwt.ts"
click node_db_init "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/config/database.ts"
click node_db_schemas "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/config/Issue.model.ts"
click node_domain_models "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/models/Issue.model.ts"
click node_s3 "https://github.com/din-esh-kumar/synergy/blob/main/backend/src/utils/s3.ts"

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_fe_main,node_fe_app,node_fe_router,node_fe_context,node_fe_hooks,node_fe_services,node_fe_api,node_fe_contracts toneBlue
class node_be_server,node_be_app,node_be_routes,node_be_protection,node_be_controllers,node_be_jwt,node_s3 toneAmber
class node_db_init,node_db_schemas,node_domain_models toneMint
```

## Components

### React SPA

- [SPA bootstrap](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/main.tsx): Vite entry · `frontend/src/main.tsx`
- [Application shell](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/App.tsx): React root · `frontend/src/App.tsx`
- [Route boundary](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/router.tsx): React router · Authenticated views consume shared auth state. · `frontend/src/router.tsx`
- [Auth and theme state](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/context/AuthContext.tsx): React contexts · `frontend/src/context/AuthContext.tsx`
- [Domain data hooks](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/hooks/useIssues.ts): feature hooks · Issues, projects, and users UI state. · `frontend/src/hooks/useIssues.ts`
- [Domain API services](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/services/issue.service.ts): service layer · Auth, issue, project, and update endpoint wrappers. · `frontend/src/services/issue.service.ts`
- [HTTP client](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/services/api.ts): API client · `frontend/src/services/api.ts`
- [Frontend contracts](https://github.com/din-esh-kumar/synergy/blob/main/frontend/src/types/issue.types.ts): TypeScript types · Auth, issue, and project API/domain contracts. · `frontend/src/types/issue.types.ts`

### HTTP API

- [API process startup](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/server.ts): server entry · `backend/src/server.ts`
- [HTTP application](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/app.ts): app composition · Composes middleware and route modules. · `backend/src/app.ts`
- [Capability routes](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/routes/auth.routes.ts): route modules · Auth, project, issue, and update route matching. · `backend/src/routes/auth.routes.ts`
- [Request protection](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/middleware/auth.middleware.ts): middleware chain · JWT auth, role policy, validation, and centralized errors. · `backend/src/middleware/auth.middleware.ts`
- [Domain controllers](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/controllers/issue.controller.ts): controllers · Auth, project, issue, and update request boundary. · `backend/src/controllers/issue.controller.ts`
- [JWT utility](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/utils/jwt.ts): token utility · `backend/src/utils/jwt.ts`
- [Object storage](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/utils/s3.ts): S3 integration · Storage remains behind the utility boundary. · `backend/src/utils/s3.ts`

### Persistence

- [Database connection](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/config/database.ts): database initialization · `backend/src/config/database.ts`
- [Configured schemas](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/config/Issue.model.ts): persistence models · User, project, issue, task, team, settings, audit, and update schemas. · `backend/src/config/Issue.model.ts`
- [Controller-facing models](https://github.com/din-esh-kumar/synergy/blob/main/backend/src/models/Issue.model.ts): domain models · Parallel model set; ownership versus configured schemas needs resolution. · `backend/src/models/Issue.model.ts`

## Connections

- SPA bootstrap → Application shell: mounts
- Application shell → Route boundary: renders
- Application shell → Auth and theme state: provides
- Route boundary → Domain data hooks: drives views
- Domain data hooks → Domain API services: loads and mutates
- Domain API services → HTTP client: uses
- Domain API services → Frontend contracts: uses contracts
- HTTP client → HTTP application: HTTP API
- API process startup → HTTP application: starts
- HTTP application → Capability routes: mounts
- Capability routes → Request protection: applies
- Request protection → JWT utility: verifies tokens
- Request protection → Domain controllers: authorizes and validates
- Domain controllers → Controller-facing models: uses
- Controller-facing models → Configured schemas: parallel ownership
- Configured schemas → Database connection: connects through
- Domain controllers → Object storage: file storage