# dharani525/taskflow architecture

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

- Interactive diagram: https://gitdiagram.com/dharani525/taskflow
- Repository: https://github.com/dharani525/taskflow

## Overview

#### 1. System Purpose and Deployment Shape
TaskFlow is a full-stack, role-scoped team task-management system: Members manage their tasks, Managers manage direct-report tasks, and Admins manage organization-wide visibility and user assignments. It comprises a React SPA, Spring Boot REST API, and PostgreSQL persistence.
- `docker-compose.yml`
- `task-backend/Dockerfile`
- `task-frontend/Dockerfile`

#### 2. Application Entry Points
The backend starts as a Java 17 Spring Boot application; HTTP controllers expose authentication, task, and administrative APIs. The frontend is a Vite/React application bootstrapped into the browser and served in containers through Nginx.
- `task-backend/src/main/java/com/backend/taskflow/TaskflowApplication.java`
- `task-frontend/src/main.jsx`
- `task-frontend/src/App.jsx`
- `task-frontend/nginx.conf`

#### 3. Authentication and Authorization Boundary
Unauthenticated registration/login flows issue JWTs. For protected API requests, the Spring Security filter extracts and validates the JWT, loads user details, and establishes the security context. Security configuration also defines CORS and endpoint access rules. The client persists auth state locally and attaches credentials through its API service; private routing gates protected UI.
- `task-backend/src/main/java/com/backend/taskflow/config/SecurityConfig.java`
- `task-backend/src/main/java/com/backend/taskflow/security/JwtAuthenticationFilter.java`
- `task-backend/src/main/java/com/backend/taskflow/security/JwtTokenProvider.java`
- `task-frontend/src/context/AuthProvider.jsx`
- `task-frontend/src/components/auth/PrivateRoute.jsx`
- `task-frontend/src/services/api.js`

#### 4. Backend API and Domain Services
Controllers form the REST boundary and delegate business behavior to services. `AuthService` handles user registration/login; `TaskService` applies role-aware task visibility and mutation authorization; `AdminController` exposes privileged role and manager assignment operations. DTOs separate API payloads from persistence entities, while centralized exception handling standardizes error responses.
- `task-backend/src/main/java/com/backend/taskflow/controller/AuthController.java`
- `task-backend/src/main/java/com/backend/taskflow/controller/TaskController.java`
- `task-backend/src/main/java/com/backend/taskflow/controller/AdminController.java`
- `task-backend/src/main/java/com/backend/taskflow/service/AuthService.java`
- `task-backend/src/main/java/com/backend/taskflow/service/TaskService.java`
- `task-backend/src/main/java/com/backend/taskflow/exception/GlobalExceptionHandler.java`

#### 5. Persistence and Access-Control Data Model
JPA entities model `User` and `Task`. A user has a role and optional self-referential manager relationship; a task belongs to an owner and carries status, priority, and due-date state. Repository access is the persistence boundary to PostgreSQL. Role-scoped service logic derives accessible tasks from owner, direct-report, or global scope.
- `task-backend/src/main/java/com/backend/taskflow/entity/User.java`
- `task-backend/src/main/java/com/backend/taskflow/entity/Task.java`
- `task-backend/src/main/java/com/backend/taskflow/entity/Role.java`
- `task-backend/src/main/java/com/backend/taskflow/repository/UserRepository.java`
- `task-backend/src/main/java/com/backend/taskflow/repository/TaskRepository.java`

#### 6. Frontend Task Workflow
Authenticated users enter role-oriented dashboard/panel layouts, which host the Kanban board. The board loads visible tasks from the API, groups them into status columns, and uses drag-and-drop to drive task status updates. Task creation, edit, and detail interactions converge in form/modal components and invoke backend CRUD APIs.
- `task-frontend/src/components/layout/Dashboard.jsx`
- `task-frontend/src/components/layout/AdminPanel.jsx`
- `task-frontend/src/components/tasks/TaskBoard.jsx`
- `task-frontend/src/components/tasks/TaskColumn.jsx`
- `task-frontend/src/components/tasks/TaskForm.jsx`
- `task-frontend/src/components/tasks/TaskModal.jsx`

#### 7. Runtime Integrations
Backend runtime configuration supplies PostgreSQL connection settings, JWT secret, and allowed frontend origins. PostgreSQL may be local or Supabase-hosted. OpenAPI configuration provides Swagger documentation with bearer-token support. GitHub Actions separately validates backend tests and frontend builds.
- `task-backend/src/main/resources/application.yaml`
- `task-backend/src/main/java/com/backend/taskflow/config/OpenApiConfig.java`
- `.github/workflows/backend-ci.yml`
- `.github/workflows/frontend-ci.yml`

Main entry points: [`task-backend/src/main/java/com/backend/taskflow/controller/TaskController.java`](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/controller/TaskController.java) (REST controllers), [`task-backend/src/main/java/com/backend/taskflow/repository/TaskRepository.java`](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/repository/TaskRepository.java) (JPA repositories), [`docker-compose.yml`](https://github.com/dharani525/taskflow/blob/main/docker-compose.yml) (Container stack), [`task-frontend/src/App.jsx`](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/App.jsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_browser["Browser SPA<br/>React/Vite client<br/>[main.jsx]"]
  node_app["App routes<br/>React application<br/>[App.jsx]"]
  node_auth_client["Auth state &amp; API client<br/>client auth boundary<br/>[AuthProvider.jsx]"]
  node_private_route["Private routes<br/>route guard<br/>[PrivateRoute.jsx]"]
  node_dashboard["Role dashboards<br/>UI layouts<br/>[Dashboard.jsx]"]
  node_task_board["Kanban task workflow<br/>task UI<br/>[TaskBoard.jsx]"]
end

subgraph group_backend["Spring Boot backend"]
  node_api["REST controllers<br/>HTTP API"]
  node_security["JWT security filter<br/>Spring Security"]
  node_jwt["JWT token provider<br/>token service"]
  node_auth_service["Authentication service<br/>domain service<br/>[AuthService.java]"]
  node_task_service["Role-scoped task service<br/>domain service<br/>[TaskService.java]"]
  node_errors["Exception handler<br/>API error boundary"]
  node_openapi["OpenAPI / Swagger<br/>API documentation<br/>[OpenApiConfig.java]"]
end

subgraph group_data["Persistence"]
  node_repositories["JPA repositories<br/>persistence access"]
  node_domain["Users, roles &amp; tasks<br/>JPA domain model<br/>[Task.java]"]
  node_postgres[("PostgreSQL<br/>relational database")]
end

subgraph group_runtime["Deployment"]
  node_compose{{"Container stack<br/>Docker Compose<br/>[docker-compose.yml]"}}
  node_nginx["Nginx frontend server<br/>static web server<br/>[nginx.conf]"]
  node_backend_app["Spring Boot runtime<br/>Java application"]
end

node_browser -->|"boots"| node_app
node_app -->|"uses"| node_auth_client
node_app -->|"guards"| node_private_route
node_private_route -->|"admits authenticated users"| node_dashboard
node_dashboard -->|"hosts"| node_task_board
node_task_board -->|"task API calls"| node_auth_client
node_auth_client -->|"JWT-authenticated HTTP"| node_api
node_api -->|"protected requests"| node_security
node_security -->|"validates token"| node_jwt
node_api -->|"registration / login"| node_auth_service
node_auth_service -->|"issues token"| node_jwt
node_api -->|"task operations"| node_task_service
node_api -.->|"maps failures"| node_errors
node_auth_service -->|"users"| node_repositories
node_task_service -->|"scoped queries &amp; updates"| node_repositories
node_repositories -->|"maps"| node_domain
node_repositories -->|"JPA persistence"| node_postgres
node_backend_app -->|"hosts"| node_api
node_openapi -.->|"documents"| node_api
node_compose -->|"runs"| node_nginx
node_compose -->|"runs"| node_backend_app
node_compose -->|"runs or connects"| node_postgres
node_nginx -->|"serves SPA assets"| node_browser

click node_browser "https://github.com/dharani525/taskflow/blob/main/task-frontend/src/main.jsx"
click node_app "https://github.com/dharani525/taskflow/blob/main/task-frontend/src/App.jsx"
click node_auth_client "https://github.com/dharani525/taskflow/blob/main/task-frontend/src/context/AuthProvider.jsx"
click node_private_route "https://github.com/dharani525/taskflow/blob/main/task-frontend/src/components/auth/PrivateRoute.jsx"
click node_dashboard "https://github.com/dharani525/taskflow/blob/main/task-frontend/src/components/layout/Dashboard.jsx"
click node_task_board "https://github.com/dharani525/taskflow/blob/main/task-frontend/src/components/tasks/TaskBoard.jsx"
click node_api "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/controller/TaskController.java"
click node_security "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/security/JwtAuthenticationFilter.java"
click node_jwt "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/security/JwtTokenProvider.java"
click node_auth_service "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/service/AuthService.java"
click node_task_service "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/service/TaskService.java"
click node_errors "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/exception/GlobalExceptionHandler.java"
click node_repositories "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/repository/TaskRepository.java"
click node_domain "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/entity/Task.java"
click node_compose "https://github.com/dharani525/taskflow/blob/main/docker-compose.yml"
click node_nginx "https://github.com/dharani525/taskflow/blob/main/task-frontend/nginx.conf"
click node_backend_app "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/TaskflowApplication.java"
click node_openapi "https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/config/OpenApiConfig.java"

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_browser,node_app,node_auth_client,node_private_route,node_dashboard,node_task_board toneBlue
class node_api,node_security,node_jwt,node_auth_service,node_task_service,node_errors,node_openapi toneAmber
class node_repositories,node_domain,node_postgres toneMint
class node_compose,node_nginx,node_backend_app toneRose
```

## Components

### React frontend

- [Browser SPA](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/main.jsx): React/Vite client · `task-frontend/src/main.jsx`
- [App routes](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/App.jsx): React application · `task-frontend/src/App.jsx`
- [Auth state & API client](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/context/AuthProvider.jsx): client auth boundary · Persists credentials and attaches JWTs to API requests. · `task-frontend/src/context/AuthProvider.jsx`
- [Private routes](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/components/auth/PrivateRoute.jsx): route guard · `task-frontend/src/components/auth/PrivateRoute.jsx`
- [Role dashboards](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/components/layout/Dashboard.jsx): UI layouts · Member/manager dashboard and admin panel entry layouts. · `task-frontend/src/components/layout/Dashboard.jsx`
- [Kanban task workflow](https://github.com/dharani525/taskflow/blob/main/task-frontend/src/components/tasks/TaskBoard.jsx): task UI · Loads scoped tasks and drives CRUD and status changes. · `task-frontend/src/components/tasks/TaskBoard.jsx`

### Spring Boot backend

- [REST controllers](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/controller/TaskController.java): HTTP API · Authentication, task, and privileged administration endpoints. · `task-backend/src/main/java/com/backend/taskflow/controller/TaskController.java`
- [JWT security filter](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/security/JwtAuthenticationFilter.java): Spring Security · Validates bearer tokens and establishes the security context. · `task-backend/src/main/java/com/backend/taskflow/security/JwtAuthenticationFilter.java`
- [JWT token provider](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/security/JwtTokenProvider.java): token service · `task-backend/src/main/java/com/backend/taskflow/security/JwtTokenProvider.java`
- [Authentication service](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/service/AuthService.java): domain service · Registers users and authenticates login requests. · `task-backend/src/main/java/com/backend/taskflow/service/AuthService.java`
- [Role-scoped task service](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/service/TaskService.java): domain service · Enforces owner, direct-report, and organization task scope. · `task-backend/src/main/java/com/backend/taskflow/service/TaskService.java`
- [Exception handler](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/exception/GlobalExceptionHandler.java): API error boundary · Standardizes REST error responses. · `task-backend/src/main/java/com/backend/taskflow/exception/GlobalExceptionHandler.java`
- [OpenAPI / Swagger](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/config/OpenApiConfig.java): API documentation · Documents bearer-authenticated API operations. · `task-backend/src/main/java/com/backend/taskflow/config/OpenApiConfig.java`

### Persistence

- [JPA repositories](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/repository/TaskRepository.java): persistence access · User and task repository boundary. · `task-backend/src/main/java/com/backend/taskflow/repository/TaskRepository.java`
- [Users, roles & tasks](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/entity/Task.java): JPA domain model · Users can report to managers; tasks belong to owners and carry workflow state. · `task-backend/src/main/java/com/backend/taskflow/entity/Task.java`
- **PostgreSQL**: relational database · Local or Supabase-hosted persistence.

### Deployment

- [Container stack](https://github.com/dharani525/taskflow/blob/main/docker-compose.yml): Docker Compose · Deploys the frontend, backend, and database runtime. · `docker-compose.yml`
- [Nginx frontend server](https://github.com/dharani525/taskflow/blob/main/task-frontend/nginx.conf): static web server · Serves the built SPA in the frontend container. · `task-frontend/nginx.conf`
- [Spring Boot runtime](https://github.com/dharani525/taskflow/blob/main/task-backend/src/main/java/com/backend/taskflow/TaskflowApplication.java): Java application · `task-backend/src/main/java/com/backend/taskflow/TaskflowApplication.java`

## Connections

- Browser SPA → App routes: boots
- App routes → Auth state & API client: uses
- App routes → Private routes: guards
- Private routes → Role dashboards: admits authenticated users
- Role dashboards → Kanban task workflow: hosts
- Kanban task workflow → Auth state & API client: task API calls
- Auth state & API client → REST controllers: JWT-authenticated HTTP
- REST controllers → JWT security filter: protected requests
- JWT security filter → JWT token provider: validates token
- REST controllers → Authentication service: registration / login
- Authentication service → JWT token provider: issues token
- REST controllers → Role-scoped task service: task operations
- REST controllers → Exception handler: maps failures
- Authentication service → JPA repositories: users
- Role-scoped task service → JPA repositories: scoped queries & updates
- JPA repositories → Users, roles & tasks: maps
- JPA repositories → PostgreSQL: JPA persistence
- Spring Boot runtime → REST controllers: hosts
- OpenAPI / Swagger → REST controllers: documents
- Container stack → Nginx frontend server: runs
- Container stack → Spring Boot runtime: runs
- Container stack → PostgreSQL: runs or connects
- Nginx frontend server → Browser SPA: serves SPA assets