# javierdvlpr/taskflow architecture

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

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

## Overview

1. **Overall shape**
TaskFlow PRO is a two-tier enterprise task management system: an Angular 17 single-page frontend talks to a Spring Boot 3.2 REST backend, which persists data in PostgreSQL. The architectural boundary is cleanly split into UI/client concerns and server-side business/security/data concerns.

2. **Frontend subsystem**
The frontend is organized by feature area under `src/app/features`: `auth`, `admin`, `employee`, and a role-based `dashboard` redirect. It uses standalone components, Angular routing, shared layout/loading components, and a central auth service/interceptor pattern. This makes the UI primarily a presentation and session-management layer.

3. **Frontend access control**
Two client-side guards define navigation boundaries: `auth.guard.ts` protects authenticated routes, and `role.guard.ts` constrains admin vs employee views. The `auth.interceptor.ts` attaches authentication tokens to API calls, so the frontend is responsible for carrying session identity across requests but not enforcing server trust.

4. **Backend API layer**
The backend exposes REST controllers for `Auth`, `User`, `Department`, `Task`, and `TimeLog`. These controllers represent the public API surface and map incoming HTTP requests into DTOs and service calls rather than directly exposing entities.

5. **Backend application layers**
The backend follows a typical layered Spring structure: `controller -> service -> repository -> entity`. Services contain business rules, repositories handle persistence, and entities model the domain. DTOs (`TaskDTO`, `UserDTO`, response/request objects) separate API payloads from internal JPA entities.

6. **Security boundary**
Authentication is JWT-based. `SecurityConfig`, `JwtService`, `JwtAuthenticationFilter`, and `CustomUserDetailsService` form the security subsystem that authenticates requests, resolves the current user, and protects routes by role. This is the main trust boundary between client and server.

7. **Domain model**
The core business entities are `User`, `Department`, `Task`, and `TimeLog`, with supporting enums for `UserRole`, `TaskStatus`, and `Priority`. This shows the system centers on assigning work, organizing people into departments, and recording execution time against tasks.

8. **Main data flows**
The primary flow is: login request from Angular -> AuthController/AuthService -> JWT issuance -> frontend stores and reuses token -> subsequent API calls go through the interceptor -> JWT filter validates identity -> services load/update domain data through repositories. For regular operations, the same pattern applies to task assignment, task viewing, user management, department management, and time logging.

9. **Role-based business partitioning**
The application is split into two product experiences: administrators manage users, departments, tasks, and reports; employees view assigned tasks, track time, and review history. This role split is reflected both in the frontend routes/components and in backend authorization decisions.

10. **Persistence and initialization**
Data access is abstracted through Spring Data repositories for users, departments, tasks, and time logs. `DataInitializer` seeds initial data, likely including the sample admin/employee accounts documented in the README. A `database/clean_database.sql` file suggests support for resetting or recreating the database state.

11. **Configuration and runtime**
Backend configuration lives in `application.yml` and `.env` templates; frontend environment values live in `environment.ts`. The project expects local development via two processes: backend on port 8081 and frontend on port 4200, with Swagger UI available for API exploration.

12. **Operational entry points**
The `.bat` scripts (`start-all.bat`, `start-backend.bat`, `start-frontend.bat`) are the top-level operational wrappers. They do not add business logic, but they define how the system is launched and therefore matter for deployment/runtime diagrams.

13. **Architecture summary for diagramming**
A good diagram would show: browser/UI on the left, Angular route/guard/interceptor layer in the middle, Spring Boot API with security filter and service/repository layers on the right, and PostgreSQL at the bottom. Separate the admin and employee feature paths at the UI and authorization layers, but keep the shared backend domain and persistence layer centralized.

Main entry points: [`frontend/src/app/app.routes.ts`](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/app.routes.ts) (App Routes), [`backend/src/main/java/com/taskflow/service/AuthService.java`](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/service/AuthService.java) (Domain Services), [`backend/src/main/java/com/taskflow/controller/AuthController.java`](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/controller/AuthController.java) (REST Controllers), [`backend/src/main/java/com/taskflow/security/jwt/JwtAuthenticationFilter.java`](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/jwt/JwtAuthenticationFilter.java) (JWT Filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Angular UI"]
  node_ui["Angular SPA<br/>frontend app<br/>[app.component.ts]"]
  node_routes["App Routes<br/>navigation<br/>[app.routes.ts]"]
  node_authguard(("Auth Guard<br/>route guard<br/>[auth.guard.ts]"))
  node_roleguard(("Role Guard<br/>route guard<br/>[role.guard.ts]"))
  node_interceptor(("Auth Interceptor<br/>http interceptor"))
  node_authsvc["Auth Service<br/>session service<br/>[auth.service.ts]"]
  node_login["Login View<br/>auth screen<br/>[login.component.ts]"]
  node_admin["Admin Area<br/>feature area"]
  node_employee["Employee Area<br/>feature area"]
  node_layout["Shared Layout<br/>ui shell"]
end

subgraph group_backend["Spring API"]
  node_security["Security Config<br/>security boundary"]
  node_jwtfilter(("JWT Filter<br/>request filter"))
  node_jwtservice(("JWT Service<br/>token service<br/>[JwtService.java]"))
  node_usersvc["User Details<br/>identity service"]
  node_controllers["REST Controllers<br/>api layer"]
  node_services["Domain Services<br/>business layer<br/>[AuthService.java]"]
  node_repos[("Repositories<br/>persistence layer")]
  node_entities["Domain Model<br/>jpa entities<br/>[User.java]"]
  node_initializer(("Data Initializer<br/>bootstrap"))
end

subgraph group_data["Data Layer"]
  node_db[("PostgreSQL<br/>database<br/>[clean_database.sql]")]
  node_config["App Config<br/>runtime config<br/>[application.yml]"]
end

subgraph group_ops["Runtime"]
  node_launcher["Start Scripts<br/>ops wrapper<br/>[start-all.bat]"]
end

node_ui -->|"uses"| node_routes
node_routes -->|"protects"| node_authguard
node_routes -->|"filters"| node_roleguard
node_routes -->|"opens"| node_login
node_routes -->|"navigates"| node_admin
node_routes -->|"navigates"| node_employee
node_layout -->|"wraps"| node_admin
node_layout -->|"wraps"| node_employee
node_login -->|"calls"| node_authsvc
node_authsvc -->|"stores token"| node_interceptor
node_interceptor -->|"calls API"| node_controllers
node_controllers -->|"delegates"| node_services
node_services -->|"persists via"| node_repos
node_repos -->|"maps"| node_entities
node_services -->|"uses"| node_entities
node_security -->|"installs"| node_jwtfilter
node_jwtfilter -->|"validates"| node_jwtservice
node_jwtfilter -->|"loads identity"| node_usersvc
node_controllers -->|"protected by"| node_security
node_initializer -->|"seeds"| node_db
node_services -->|"reads/writes"| node_db
node_config -->|"configures"| node_security
node_launcher -->|"starts"| node_ui
node_launcher -->|"starts"| node_controllers

click node_ui "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/app.component.ts"
click node_routes "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/app.routes.ts"
click node_authguard "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/guards/auth.guard.ts"
click node_roleguard "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/guards/role.guard.ts"
click node_interceptor "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/services/auth.interceptor.ts"
click node_authsvc "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/services/auth.service.ts"
click node_login "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/features/auth/login/login.component.ts"
click node_admin "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/features/admin/dashboard/admin-dashboard.component.ts"
click node_employee "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/features/employee/dashboard/employee-dashboard.component.ts"
click node_layout "https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/shared/components/layout/layout.component.ts"
click node_security "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/SecurityConfig.java"
click node_jwtfilter "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/jwt/JwtAuthenticationFilter.java"
click node_jwtservice "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/jwt/JwtService.java"
click node_usersvc "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/CustomUserDetailsService.java"
click node_controllers "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/controller/AuthController.java"
click node_services "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/service/AuthService.java"
click node_repos "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/repository/UserRepository.java"
click node_entities "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/entity/User.java"
click node_initializer "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/config/DataInitializer.java"
click node_db "https://github.com/javierdvlpr/taskflow/blob/main/database/clean_database.sql"
click node_config "https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/resources/application.yml"
click node_launcher "https://github.com/javierdvlpr/taskflow/blob/main/start-all.bat"

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_ui,node_routes,node_authguard,node_roleguard,node_interceptor,node_authsvc,node_login,node_admin,node_employee,node_layout toneBlue
class node_security,node_jwtfilter,node_jwtservice,node_usersvc,node_controllers,node_services,node_repos,node_entities,node_initializer toneAmber
class node_db,node_config toneMint
class node_launcher toneRose
```

## Components

### Angular UI

Client-side task management experience and navigation control

- [Angular SPA](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/app.component.ts): frontend app · Single-page client for admin and employee workflows · `frontend/src/app/app.component.ts`
- [App Routes](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/app.routes.ts): navigation · Top-level route configuration and redirects · `frontend/src/app/app.routes.ts`
- [Auth Guard](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/guards/auth.guard.ts): route guard · Blocks unauthenticated access · `frontend/src/app/core/guards/auth.guard.ts`
- [Role Guard](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/guards/role.guard.ts): route guard · Constrains admin and employee views · `frontend/src/app/core/guards/role.guard.ts`
- [Auth Interceptor](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/services/auth.interceptor.ts): http interceptor · Attaches JWT to API requests · `frontend/src/app/core/services/auth.interceptor.ts`
- [Auth Service](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/core/services/auth.service.ts): session service · Handles login, token state, and session identity · `frontend/src/app/core/services/auth.service.ts`
- [Login View](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/features/auth/login/login.component.ts): auth screen · Entry point for user authentication · `frontend/src/app/features/auth/login/login.component.ts`
- [Admin Area](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/features/admin/dashboard/admin-dashboard.component.ts): feature area · User, department, task, and report management · `frontend/src/app/features/admin/dashboard/admin-dashboard.component.ts`
- [Employee Area](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/features/employee/dashboard/employee-dashboard.component.ts): feature area · My tasks, time tracking, and history views · `frontend/src/app/features/employee/dashboard/employee-dashboard.component.ts`
- [Shared Layout](https://github.com/javierdvlpr/taskflow/blob/main/frontend/src/app/shared/components/layout/layout.component.ts): ui shell · Common app shell and loading state components · `frontend/src/app/shared/components/layout/layout.component.ts`

### Spring API

REST API, security, services, and persistence

- [Security Config](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/SecurityConfig.java): security boundary · HTTP access rules and authentication setup · `backend/src/main/java/com/taskflow/security/SecurityConfig.java`
- [JWT Filter](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/jwt/JwtAuthenticationFilter.java): request filter · Validates bearer tokens on incoming requests · `backend/src/main/java/com/taskflow/security/jwt/JwtAuthenticationFilter.java`
- [JWT Service](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/jwt/JwtService.java): token service · Creates and validates JWTs · `backend/src/main/java/com/taskflow/security/jwt/JwtService.java`
- [User Details](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/security/CustomUserDetailsService.java): identity service · Loads authenticated user details for security · `backend/src/main/java/com/taskflow/security/CustomUserDetailsService.java`
- [REST Controllers](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/controller/AuthController.java): api layer · Auth, user, department, task, and time-log endpoints · `backend/src/main/java/com/taskflow/controller/AuthController.java`
- [Domain Services](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/service/AuthService.java): business layer · Business rules for auth, users, departments, tasks, and time logs · `backend/src/main/java/com/taskflow/service/AuthService.java`
- [Repositories](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/repository/UserRepository.java): persistence layer · Spring Data repositories for domain aggregates · `backend/src/main/java/com/taskflow/repository/UserRepository.java`
- [Domain Model](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/entity/User.java): jpa entities · Users, departments, tasks, time logs, and enums · `backend/src/main/java/com/taskflow/entity/User.java`
- [Data Initializer](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/java/com/taskflow/config/DataInitializer.java): bootstrap · Seeds initial application data · `backend/src/main/java/com/taskflow/config/DataInitializer.java`

### Data Layer

Database and initialization assets

- [PostgreSQL](https://github.com/javierdvlpr/taskflow/blob/main/database/clean_database.sql): database · Persistent store for application data · `database/clean_database.sql`
- [App Config](https://github.com/javierdvlpr/taskflow/blob/main/backend/src/main/resources/application.yml): runtime config · Backend and frontend environment configuration · `backend/src/main/resources/application.yml`

### Runtime

Top-level launch scripts

- [Start Scripts](https://github.com/javierdvlpr/taskflow/blob/main/start-all.bat): ops wrapper · Batch scripts for launching backend and frontend · `start-all.bat`

## Connections

- Angular SPA → App Routes: uses · App shell is driven by route configuration
- App Routes → Auth Guard: protects · Authenticated routes are guarded
- App Routes → Role Guard: filters · Role-based access is applied per route
- App Routes → Login View: opens · Unauthenticated users land on login
- App Routes → Admin Area: navigates · Admin role routes to admin area
- App Routes → Employee Area: navigates · Employee role routes to employee area
- Shared Layout → Admin Area: wraps · Shared shell hosts admin views
- Shared Layout → Employee Area: wraps · Shared shell hosts employee views
- Login View → Auth Service: calls · Login submits credentials through auth service
- Auth Service → Auth Interceptor: stores token · Session token is reused for API calls
- Auth Interceptor → REST Controllers: calls API · Adds auth to backend requests
- REST Controllers → Domain Services: delegates · Controllers map HTTP to business logic
- Domain Services → Repositories: persists via · Services use repositories for data access
- Repositories → Domain Model: maps · Repositories operate on domain entities
- Domain Services → Domain Model: uses · Business logic reads and updates domain objects
- Security Config → JWT Filter: installs · Security chain includes JWT validation
- JWT Filter → JWT Service: validates · Filter checks tokens using JWT service
- JWT Filter → User Details: loads identity · Authenticated principal is resolved from user details service
- REST Controllers → Security Config: protected by · API endpoints are secured by Spring Security
- Data Initializer → PostgreSQL: seeds · Bootstrap data is written to the database
- Domain Services → PostgreSQL: reads/writes · Domain operations ultimately persist to PostgreSQL
- App Config → Security Config: configures · Application settings shape backend runtime and security
- Start Scripts → Angular SPA: starts · Scripts launch the frontend process
- Start Scripts → REST Controllers: starts · Scripts launch the backend process
