# robertalim/fiix architecture

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

- Interactive diagram: https://gitdiagram.com/robertalim/fiix
- Repository: https://github.com/robertalim/fiix

## Overview

This appears to be a printer-maintenance and field-service application: staff manage printers and clients, schedule technician visits, record maintenance, and monitor attendance and location. The main visible workflow is dashboard access, with offline reports synchronized to maintenance APIs and persisted in the database; scheduling is a separate operational branch. Admin master data, reporting, and GPS/attendance are significant product areas in the tree, but their detailed runtime links are mostly unsampled. Dashed, uncited links mark those evidence limits.

Main entry points: [`db/index.ts`](https://github.com/robertalim/fiix/blob/main/db/index.ts) (Database Client), [`app/api/maintain/route.ts`](https://github.com/robertalim/fiix/blob/main/app/api/maintain/route.ts) (Maintenance API), [`app/api/schedule/route.ts`](https://github.com/robertalim/fiix/blob/main/app/api/schedule/route.ts) (Schedule API), [`lib/require-role.ts`](https://github.com/robertalim/fiix/blob/main/lib/require-role.ts) (Role Authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Field Operations"]
  node_dashboard["Operations Dashboard<br/>[page.tsx]"]
  node_maintenance_ui["Maintenance Entry<br/>[Maintenance.tsx]"]
  node_offline_sync["Offline Sync Engine<br/>[sync-engine.ts]"]
  node_maintenance_api["Maintenance API<br/>[route.ts]"]
  node_attendance["Attendance<br/>[attendance.ts]"]
  node_gps["GPS Monitoring<br/>[GpsMonitoring.tsx]"]
end

subgraph group_planning["Scheduling"]
  node_schedule_ui["Schedule Management<br/>[Schedule.tsx]"]
  node_schedule_api["Schedule API<br/>[route.ts]"]
  node_itinerary["Itinerary Ordering"]
end

subgraph group_admin["Administration"]
  node_master_data["Master Data Management"]
  node_client_groups["Client Groups<br/>[Clients.tsx]"]
  node_imports["Data Import<br/>[DataImport.tsx]"]
  node_reports["Reports<br/>[Report.tsx]"]
  node_monitoring["Service Monitoring<br/>[Monitoring.tsx]"]
end

subgraph group_platform["Application Platform"]
  node_authz["Role Authorization<br/>[require-role.ts]"]
  node_validation["Maintenance Validation<br/>[maintainSchema.ts]"]
end

subgraph group_data["Persistence"]
  node_db_client["Database Client<br/>[index.ts]"]
  node_schema["Domain Schema<br/>[schema.ts]"]
  node_attendance_query["Attendance Queries"]
end

node_staff(("Staff"))
node_external_auth{{"Clerk Auth"}}

node_staff -.->|"opens"| node_dashboard
node_dashboard -->|"hosts"| node_offline_sync
node_offline_sync -->|"submits reports"| node_maintenance_api
node_maintenance_api -->|"reads and writes"| node_db_client
node_maintenance_api -->|"checks roles"| node_authz
node_authz -->|"checks identity"| node_external_auth
node_authz -->|"loads user"| node_db_client
node_db_client -->|"uses schema"| node_schema
node_maintenance_api -.->|"validates input"| node_validation
node_staff -.->|"records service"| node_maintenance_ui
node_maintenance_ui -.->|"submits maintenance"| node_maintenance_api
node_staff -.->|"plans visits"| node_schedule_ui
node_schedule_ui -.->|"manages schedules"| node_schedule_api
node_schedule_api -->|"checks roles"| node_authz
node_schedule_api -.->|"reads and writes"| node_db_client
node_itinerary -.->|"updates order"| node_schedule_api
node_staff -.->|"maintains records"| node_master_data
node_master_data -.->|"persists records"| node_db_client
node_client_groups -->|"uses manager"| node_master_data
node_staff -.->|"imports records"| node_imports
node_staff -.->|"reviews results"| node_reports
node_staff -.->|"monitors service"| node_monitoring
node_dashboard -.->|"gates access"| node_attendance
node_staff -.->|"tracks field work"| node_gps
node_attendance_query -->|"queries records"| node_db_client
node_attendance_query -->|"uses attendance rules"| node_attendance

click node_dashboard "https://github.com/robertalim/fiix/blob/main/app/(root)/dashboard/page.tsx"
click node_maintenance_ui "https://github.com/robertalim/fiix/blob/main/components/pages/Maintenance.tsx"
click node_offline_sync "https://github.com/robertalim/fiix/blob/main/features/offline-sync/sync-engine.ts"
click node_maintenance_api "https://github.com/robertalim/fiix/blob/main/app/api/maintain/route.ts"
click node_attendance "https://github.com/robertalim/fiix/blob/main/lib/attendance.ts"
click node_gps "https://github.com/robertalim/fiix/blob/main/components/pages/GpsMonitoring.tsx"
click node_schedule_ui "https://github.com/robertalim/fiix/blob/main/components/pages/Schedule.tsx"
click node_schedule_api "https://github.com/robertalim/fiix/blob/main/app/api/schedule/route.ts"
click node_itinerary "https://github.com/robertalim/fiix/blob/main/components/ItinerarySequenceManager.tsx"
click node_master_data "https://github.com/robertalim/fiix/blob/main/components/MasterDataManager.tsx"
click node_client_groups "https://github.com/robertalim/fiix/blob/main/components/pages/Clients.tsx"
click node_imports "https://github.com/robertalim/fiix/blob/main/components/pages/DataImport.tsx"
click node_reports "https://github.com/robertalim/fiix/blob/main/components/pages/Report.tsx"
click node_monitoring "https://github.com/robertalim/fiix/blob/main/components/pages/Monitoring.tsx"
click node_authz "https://github.com/robertalim/fiix/blob/main/lib/require-role.ts"
click node_validation "https://github.com/robertalim/fiix/blob/main/validation/maintainSchema.ts"
click node_db_client "https://github.com/robertalim/fiix/blob/main/db/index.ts"
click node_schema "https://github.com/robertalim/fiix/blob/main/db/schema.ts"
click node_attendance_query "https://github.com/robertalim/fiix/blob/main/lib/server/attendance-report-query.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_dashboard,node_maintenance_ui,node_offline_sync,node_maintenance_api,node_attendance,node_gps toneBlue
class node_schedule_ui,node_schedule_api,node_itinerary toneAmber
class node_master_data,node_client_groups,node_imports,node_reports,node_monitoring toneMint
class node_authz,node_validation toneRose
class node_db_client,node_schema,node_attendance_query,node_staff,node_external_auth toneIndigo
```

## Components

### Field Operations

- [Operations Dashboard](https://github.com/robertalim/fiix/blob/main/app/(root)/dashboard/page.tsx): `app/(root)/dashboard/page.tsx`
- [Maintenance Entry](https://github.com/robertalim/fiix/blob/main/components/pages/Maintenance.tsx): `components/pages/Maintenance.tsx`
- [Offline Sync Engine](https://github.com/robertalim/fiix/blob/main/features/offline-sync/sync-engine.ts): `features/offline-sync/sync-engine.ts`
- [Maintenance API](https://github.com/robertalim/fiix/blob/main/app/api/maintain/route.ts): `app/api/maintain/route.ts`
- [Attendance](https://github.com/robertalim/fiix/blob/main/lib/attendance.ts): `lib/attendance.ts`
- [GPS Monitoring](https://github.com/robertalim/fiix/blob/main/components/pages/GpsMonitoring.tsx): `components/pages/GpsMonitoring.tsx`

### Scheduling

- [Schedule Management](https://github.com/robertalim/fiix/blob/main/components/pages/Schedule.tsx): `components/pages/Schedule.tsx`
- [Schedule API](https://github.com/robertalim/fiix/blob/main/app/api/schedule/route.ts): `app/api/schedule/route.ts`
- [Itinerary Ordering](https://github.com/robertalim/fiix/blob/main/components/ItinerarySequenceManager.tsx): `components/ItinerarySequenceManager.tsx`

### Administration

- [Master Data Management](https://github.com/robertalim/fiix/blob/main/components/MasterDataManager.tsx): `components/MasterDataManager.tsx`
- [Client Groups](https://github.com/robertalim/fiix/blob/main/components/pages/Clients.tsx): `components/pages/Clients.tsx`
- [Data Import](https://github.com/robertalim/fiix/blob/main/components/pages/DataImport.tsx): `components/pages/DataImport.tsx`
- [Reports](https://github.com/robertalim/fiix/blob/main/components/pages/Report.tsx): `components/pages/Report.tsx`
- [Service Monitoring](https://github.com/robertalim/fiix/blob/main/components/pages/Monitoring.tsx): `components/pages/Monitoring.tsx`

### Application Platform

- [Role Authorization](https://github.com/robertalim/fiix/blob/main/lib/require-role.ts): `lib/require-role.ts`
- [Maintenance Validation](https://github.com/robertalim/fiix/blob/main/validation/maintainSchema.ts): `validation/maintainSchema.ts`

### Persistence

- [Database Client](https://github.com/robertalim/fiix/blob/main/db/index.ts): `db/index.ts`
- [Domain Schema](https://github.com/robertalim/fiix/blob/main/db/schema.ts): `db/schema.ts`
- [Attendance Queries](https://github.com/robertalim/fiix/blob/main/lib/server/attendance-report-query.ts): `lib/server/attendance-report-query.ts`

### Other components

- **Staff**
- **Clerk Auth**

## Connections

- Staff → Operations Dashboard: opens
- Operations Dashboard → Offline Sync Engine: hosts (evidence: `app/(root)/dashboard/page.tsx`)
- Offline Sync Engine → Maintenance API: submits reports (evidence: `features/offline-sync/sync-engine.ts`)
- Maintenance API → Database Client: reads and writes (evidence: `app/api/maintain/route.ts`)
- Maintenance API → Role Authorization: checks roles (evidence: `app/api/maintain/route.ts`)
- Role Authorization → Clerk Auth: checks identity (evidence: `lib/require-role.ts`)
- Role Authorization → Database Client: loads user (evidence: `lib/require-role.ts`)
- Database Client → Domain Schema: uses schema (evidence: `db/index.ts`)
- Maintenance API → Maintenance Validation: validates input (evidence: `app/api/maintain/route.ts`)
- Staff → Maintenance Entry: records service
- Maintenance Entry → Maintenance API: submits maintenance
- Staff → Schedule Management: plans visits
- Schedule Management → Schedule API: manages schedules
- Schedule API → Role Authorization: checks roles (evidence: `app/api/schedule/route.ts`)
- Schedule API → Database Client: reads and writes (evidence: `app/api/schedule/route.ts`)
- Itinerary Ordering → Schedule API: updates order
- Staff → Master Data Management: maintains records
- Master Data Management → Database Client: persists records
- Client Groups → Master Data Management: uses manager (evidence: `components/pages/Clients.tsx`)
- Staff → Data Import: imports records
- Staff → Reports: reviews results
- Staff → Service Monitoring: monitors service
- Operations Dashboard → Attendance: gates access
- Staff → GPS Monitoring: tracks field work
- Attendance Queries → Database Client: queries records (evidence: `lib/server/attendance-report-query.ts`)
- Attendance Queries → Attendance: uses attendance rules (evidence: `lib/server/attendance-report-query.ts`)