# expertscloud/attendance-and-time-tracking-public architecture

> Architecture diagram of the GitHub repository expertscloud/attendance-and-time-tracking-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/expertscloud/attendance-and-time-tracking-public
- Repository: https://github.com/expertscloud/attendance-and-time-tracking-public

## Overview

Tickly combines an employee desktop time-tracking app, an admin management panel, and a shared AdonisJS API. Employees sign in, check in, track work against projects, pause or resume, and check out; Electron idle detection can trigger automatic pauses. Admins manage users, projects, and clients and review attendance and leave. The API validates and handles requests through controllers and services, persisting domain records in MySQL. README capabilities are included where source excerpts were not sampled; those uncertain internal links are omitted.

Main entry points: [`backend/config/database.ts`](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/config/database.ts) (MySQL database), [`admin-frontend/src/routes/routes.jsx`](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/routes/routes.jsx) (Admin application), [`backend/start/routes.ts`](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/routes.ts) (REST routes), [`frontend/src/pages/dashboard/Dashboard.jsx`](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/pages/dashboard/Dashboard.jsx) (Tracking dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_employee["Employee desktop"]
  node_desktop_app["Tracking dashboard<br/>[Dashboard.jsx]"]
  node_desktop_attendance["Attendance controls"]
  node_desktop_electron["Idle detection<br/>[main.js]"]
  node_desktop_hooks["Location and IPC"]
end

subgraph group_admin["Admin panel"]
  node_admin_routes["Admin application<br/>[routes.jsx]"]
  node_admin_users["User management<br/>[Users.jsx]"]
  node_admin_projects["Project management<br/>[Projects.jsx]"]
  node_admin_clients["Client management<br/>[Clients.jsx]"]
  node_admin_attendance["Attendance review<br/>[Attendance.jsx]"]
  node_admin_leaves["Leave management<br/>[Leaves.jsx]"]
end

subgraph group_api["Backend API"]
  node_api_routes["REST routes<br/>[routes.ts]"]
  node_attendance_routes["Attendance endpoints"]
  node_attendance_controller["Attendance controller"]
end

subgraph group_domain["Domain services"]
  node_auth_service["Authentication<br/>[auth_service.ts]"]
  node_attendance_service["Time tracking"]
  node_user_service["User service<br/>[user_service.ts]"]
  node_project_service["Project service<br/>[project_service.ts]"]
  node_client_service["Client service<br/>[client_service.ts]"]
  node_leave_services["Leave services<br/>[leave_service.ts]"]
end

subgraph group_integrations["External integrations"]
  node_mysql[("MySQL database<br/>[database.ts]")]
  node_s3[("AWS S3")]
  node_smtp["SMTP email"]
  node_cron["Automated checkout<br/>[scheduler.ts]"]
end

node_employee_actor(("Employee"))
node_admin_actor(("Admin / HR"))

node_employee_actor -->|"uses"| node_desktop_app
node_desktop_app -->|"drives"| node_desktop_attendance
node_desktop_app -->|"starts timer"| node_desktop_electron
node_desktop_electron -->|"sends idle events"| node_desktop_app
node_desktop_app -->|"requests location"| node_desktop_hooks
node_desktop_attendance -->|"calls API"| node_attendance_routes
node_desktop_hooks -->|"submits snapshots"| node_attendance_routes
node_admin_actor -->|"uses"| node_admin_routes
node_admin_routes -->|"routes to"| node_admin_users
node_admin_routes -->|"routes to"| node_admin_projects
node_admin_routes -->|"routes to"| node_admin_clients
node_admin_routes -->|"routes to"| node_admin_attendance
node_admin_routes -->|"routes to"| node_admin_leaves
node_admin_users -->|"calls API"| node_api_routes
node_admin_projects -->|"calls API"| node_api_routes
node_admin_clients -->|"calls API"| node_api_routes
node_admin_attendance -->|"calls API"| node_api_routes
node_admin_leaves -->|"calls API"| node_api_routes
node_api_routes -->|"registers"| node_attendance_routes
node_attendance_routes -->|"dispatches"| node_attendance_controller
node_attendance_controller -->|"calls"| node_attendance_service
node_attendance_controller -->|"stores snapshots"| node_mysql
node_attendance_service -->|"reads and writes"| node_mysql
node_auth_service -->|"reads and writes"| node_mysql
node_user_service -->|"reads and writes"| node_mysql
node_project_service -->|"reads and writes"| node_mysql
node_client_service -->|"reads and writes"| node_mysql
node_leave_services -->|"reads and writes"| node_mysql
node_user_service -.->|"stores profile photos"| node_s3
node_auth_service -.->|"dispatches email events"| node_smtp
node_cron -->|"closes open attendance"| node_mysql

click node_desktop_app "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/pages/dashboard/Dashboard.jsx"
click node_desktop_attendance "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/pages/dashboard/AttendanceApiCalls.js"
click node_desktop_electron "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/electron/main.js"
click node_desktop_hooks "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/hooks/useLocationSnapshot.js"
click node_admin_routes "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/routes/routes.jsx"
click node_admin_users "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/users/Users.jsx"
click node_admin_projects "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/projects/Projects.jsx"
click node_admin_clients "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/clients/Clients.jsx"
click node_admin_attendance "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/attendances/Attendance.jsx"
click node_admin_leaves "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/leaves/Leaves.jsx"
click node_api_routes "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/routes.ts"
click node_attendance_routes "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/routes/attendance_routes.ts"
click node_attendance_controller "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/controllers/attendance_controller.ts"
click node_auth_service "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/auth_service.ts"
click node_attendance_service "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/attendance_service.ts"
click node_user_service "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/user_service.ts"
click node_project_service "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/project_service.ts"
click node_client_service "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/client_service.ts"
click node_leave_services "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/leave_service.ts"
click node_mysql "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/config/database.ts"
click node_cron "https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/scheduler.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_desktop_app,node_desktop_attendance,node_desktop_electron,node_desktop_hooks toneBlue
class node_admin_routes,node_admin_users,node_admin_projects,node_admin_clients,node_admin_attendance,node_admin_leaves toneAmber
class node_api_routes,node_attendance_routes,node_attendance_controller toneMint
class node_auth_service,node_attendance_service,node_user_service,node_project_service,node_client_service,node_leave_services toneRose
class node_mysql,node_s3,node_smtp,node_cron,node_employee_actor,node_admin_actor toneIndigo
```

## Components

### Employee desktop

- [Tracking dashboard](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/pages/dashboard/Dashboard.jsx): `frontend/src/pages/dashboard/Dashboard.jsx`
- [Attendance controls](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/pages/dashboard/AttendanceApiCalls.js): `frontend/src/pages/dashboard/AttendanceApiCalls.js`
- [Idle detection](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/electron/main.js): `frontend/electron/main.js`
- [Location and IPC](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/frontend/src/hooks/useLocationSnapshot.js): `frontend/src/hooks/useLocationSnapshot.js`

### Admin panel

- [Admin application](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/routes/routes.jsx): `admin-frontend/src/routes/routes.jsx`
- [User management](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/users/Users.jsx): `admin-frontend/src/pages/users/Users.jsx`
- [Project management](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/projects/Projects.jsx): `admin-frontend/src/pages/projects/Projects.jsx`
- [Client management](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/clients/Clients.jsx): `admin-frontend/src/pages/clients/Clients.jsx`
- [Attendance review](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/attendances/Attendance.jsx): `admin-frontend/src/pages/attendances/Attendance.jsx`
- [Leave management](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/admin-frontend/src/pages/leaves/Leaves.jsx): `admin-frontend/src/pages/leaves/Leaves.jsx`

### Backend API

- [REST routes](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/routes.ts): `backend/start/routes.ts`
- [Attendance endpoints](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/routes/attendance_routes.ts): `backend/start/routes/attendance_routes.ts`
- [Attendance controller](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/controllers/attendance_controller.ts): `backend/app/controllers/attendance_controller.ts`

### Domain services

- [Authentication](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/auth_service.ts): `backend/app/services/auth_service.ts`
- [Time tracking](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/attendance_service.ts): `backend/app/services/attendance_service.ts`
- [User service](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/user_service.ts): `backend/app/services/user_service.ts`
- [Project service](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/project_service.ts): `backend/app/services/project_service.ts`
- [Client service](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/client_service.ts): `backend/app/services/client_service.ts`
- [Leave services](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/app/services/leave_service.ts): `backend/app/services/leave_service.ts`

### External integrations

- [MySQL database](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/config/database.ts): `backend/config/database.ts`
- **AWS S3**
- **SMTP email**
- [Automated checkout](https://github.com/expertscloud/attendance-and-time-tracking-public/blob/main/backend/start/scheduler.ts): `backend/start/scheduler.ts`

### Other components

- **Employee**
- **Admin / HR**

## Connections

- Employee → Tracking dashboard: uses
- Tracking dashboard → Attendance controls: drives
- Tracking dashboard → Idle detection: starts timer
- Idle detection → Tracking dashboard: sends idle events
- Tracking dashboard → Location and IPC: requests location
- Attendance controls → Attendance endpoints: calls API
- Location and IPC → Attendance endpoints: submits snapshots
- Admin / HR → Admin application: uses
- Admin application → User management: routes to
- Admin application → Project management: routes to
- Admin application → Client management: routes to
- Admin application → Attendance review: routes to
- Admin application → Leave management: routes to
- User management → REST routes: calls API
- Project management → REST routes: calls API
- Client management → REST routes: calls API
- Attendance review → REST routes: calls API
- Leave management → REST routes: calls API
- REST routes → Attendance endpoints: registers
- Attendance endpoints → Attendance controller: dispatches
- Attendance controller → Time tracking: calls
- Attendance controller → MySQL database: stores snapshots
- Time tracking → MySQL database: reads and writes
- Authentication → MySQL database: reads and writes
- User service → MySQL database: reads and writes
- Project service → MySQL database: reads and writes
- Client service → MySQL database: reads and writes
- Leave services → MySQL database: reads and writes
- User service → AWS S3: stores profile photos
- Authentication → SMTP email: dispatches email events
- Automated checkout → MySQL database: closes open attendance