# najibcode/ibuild architecture

> Architecture diagram of the GitHub repository najibcode/ibuild, 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/najibcode/ibuild
- Repository: https://github.com/najibcode/ibuild

## Overview

#### Purpose and Entry Points
IBUILD ERP is an internal, multi-platform construction-operations system for supervisors and owners. Flutter is the client runtime for web, Android, iOS, desktop; its application entry point is `lib/main.dart`. Routing and adaptive shell/layout boundaries are centralized in `lib/core/routing/router.dart`, `lib/mobile_dashboard.dart`, and `lib/web_dashboard.dart`.

#### Application Composition
The codebase is organized primarily by feature, commonly separating data models/repositories, domain repository contracts, and Riverpod-backed presentation controllers/screens. A typical flow is screen → controller → repository interface/implementation → Supabase. Examples: `lib/features/projects/presentation/controllers/project_controller.dart`, `lib/features/projects/domain/repositories/project_repository.dart`, and `lib/features/projects/data/repositories/supabase_project_repository.dart`.

#### Identity, Authorization, and Navigation
Authentication is isolated behind an implementation and domain contract, with login, recovery, and startup screens under `lib/features/auth/data/repositories/auth_repository_impl.dart`, `lib/features/auth/presentation/controllers/auth_controller.dart`, and `lib/features/auth/presentation/screens/splash_screen.dart`. RBAC supplies role/permission models, a Supabase role repository, and UI guards for restricting sensitive features: `lib/features/rbac/data/repositories/supabase_role_repository.dart`, `lib/features/rbac/presentation/providers/permission_provider.dart`, and `lib/features/rbac/presentation/widgets/permission_guard.dart`.

#### Operational Domain Modules
Projects provide the central site/project identifier used to connect operational records and project dashboards: `lib/features/projects/data/models/project_model.dart`, `lib/features/projects/presentation/screens/project_operations_screen.dart`, and `lib/features/projects/data/repositories/project_dashboard_repository.dart`. Workforce workflows cover employees, attendance, daily wages, and reports through `lib/features/employees/data/repositories/supabase_employee_repository.dart`, `lib/features/attendance/presentation/controllers/attendance_controller.dart`, and `lib/features/attendance/data/services/attendance_report_service.dart`. Site execution tracks daily progress, activities, checklists, drawings, and tickets, including evidence-oriented models/repositories such as `lib/features/daily_progress/data/repositories/supabase_daily_progress_repository.dart`, `lib/features/drawings/data/repositories/supabase_drawing_repository.dart`, and `lib/features/tickets/data/repositories/supabase_ticket_repository.dart`.

#### Commercial, Asset, and Reporting Workflows
Financial workflows include expenses, billing, quotations, sales bills, payments, and ledger documents: `lib/features/expenses/data/repositories/supabase_expense_repository.dart`, `lib/features/billing/data/building_pdf_generator.dart`, and `lib/features/payments/data/payment_ledger_pdf_generator.dart`. Inventory and equipment track stock/history and fleet placement: `lib/features/inventory/data/repositories/supabase_inventory_repository.dart`, `lib/features/inventory/presentation/screens/inventory_history_screen.dart`, and `lib/features/equipment/data/repositories/supabase_equipment_repository.dart`. Shared export capabilities produce PDF/Excel outputs via `lib/core/services/generic_pdf_table_generator.dart`, `lib/core/services/excel_generator_service.dart`, and `lib/features/reports/data/pdf_report_generator.dart`.

#### Backend, Media, and Schema Boundary
Supabase is the external system of record for PostgreSQL data, Auth, RLS enforcement, and storage; the client integration boundary is `lib/core/supabase/supabase_client.provider.dart`. Versioned SQL migrations define the evolving relational schema and policies: `supabase/migrations/001_rbac_tables.sql`, `supabase/migrations/003_project_operations.sql`, and `supabase/migrations/005_supervision_and_evidence.sql`. Image uploads use ImageKit as a separate media service, with client services and a Supabase Edge Function that issues ImageKit authentication: `lib/core/image/imagekit_auth_service.dart`, `lib/services/imagekit/imagekit_service.dart`, and `supabase/functions/imagekit-auth/index.ts`.

#### Delivery and Platform Infrastructure
Web is deployed as a Flutter SPA to Vercel, configured by `vercel.json`; all routes rewrite to the client application. Native launchers package the same Flutter runtime for Android and iOS through `android/app/src/main/kotlin/com/example/ibuild/MainActivity.kt` and `ios/Runner/AppDelegate.swift`. CI runs through GitHub Actions at `.github/workflows/dart.yml`.

Main entry points: [`lib/core/routing/router.dart`](https://github.com/najibcode/ibuild/blob/main/lib/core/routing/router.dart) (Routing & adaptive shell), [`lib/core/supabase/supabase_client.provider.dart`](https://github.com/najibcode/ibuild/blob/main/lib/core/supabase/supabase_client.provider.dart) (Supabase client boundary), [`lib/features/daily_progress/data/repositories/supabase_daily_progress_repository.dart`](https://github.com/najibcode/ibuild/blob/main/lib/features/daily_progress/data/repositories/supabase_daily_progress_repository.dart) (Site execution), [`lib/features/expenses/data/repositories/supabase_expense_repository.dart`](https://github.com/najibcode/ibuild/blob/main/lib/features/expenses/data/repositories/supabase_expense_repository.dart) (Finance & billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter Client"]
  node_flutter_entry{{"Flutter entry<br/>application entry<br/>[main.dart]"}}
  node_routing_shell["Routing &amp; adaptive shell<br/>navigation boundary<br/>[router.dart]"]
end

subgraph group_access["Access Control"]
  node_auth_controller["Auth controller<br/>Riverpod controller"]
  node_auth_repository["Auth repository<br/>auth implementation"]
  node_permission_guard["Permission guard<br/>UI authorization guard"]
  node_role_repository["Role repository<br/>RBAC data repository"]
end

subgraph group_operations["Operational Modules"]
  node_projects["Projects &amp; operations<br/>central domain module"]
  node_project_controller["Project controller<br/>Riverpod controller"]
  node_project_repository["Project repository<br/>repository implementation"]
  node_workforce["Workforce &amp; attendance<br/>operational module"]
  node_site_execution["Site execution<br/>operational module"]
end

subgraph group_commercial["Commercial &amp; Assets"]
  node_commercial["Finance &amp; billing<br/>commercial module"]
  node_inventory_equipment["Inventory &amp; equipment<br/>asset module"]
  node_export_services["PDF &amp; Excel exports<br/>document service"]
end

subgraph group_platform["Platform Services"]
  node_supabase_client["Supabase client boundary<br/>backend integration"]
  node_supabase[("Supabase<br/>system of record")]
  node_schema_migrations["SQL schema &amp; policies<br/>database migrations"]
  node_imagekit_service["ImageKit media service<br/>media integration"]
  node_imagekit_auth_function{{"ImageKit auth function<br/>Supabase Edge Function<br/>[index.ts]"}}
  node_imagekit[("ImageKit<br/>media storage service")]
  node_delivery["Web, native &amp; CI delivery<br/>deployment infrastructure<br/>[vercel.json]"]
end

node_flutter_entry -->|"starts"| node_routing_shell
node_routing_shell -->|"auth flow"| node_auth_controller
node_routing_shell -->|"navigates"| node_projects
node_routing_shell -->|"navigates"| node_workforce
node_routing_shell -->|"navigates"| node_site_execution
node_routing_shell -->|"navigates"| node_commercial
node_routing_shell -->|"navigates"| node_inventory_equipment
node_auth_controller -->|"uses"| node_auth_repository
node_auth_repository -->|"auth API"| node_supabase_client
node_permission_guard -->|"checks permissions"| node_role_repository
node_role_repository -->|"queries roles"| node_supabase_client
node_projects -->|"drives"| node_project_controller
node_project_controller -->|"uses"| node_project_repository
node_project_repository -->|"persists projects"| node_supabase_client
node_workforce -->|"persists records"| node_supabase_client
node_site_execution -->|"persists evidence"| node_supabase_client
node_commercial -->|"persists transactions"| node_supabase_client
node_inventory_equipment -->|"persists assets"| node_supabase_client
node_commercial -->|"generates documents"| node_export_services
node_supabase_client -->|"connects to"| node_supabase
node_schema_migrations -->|"defines schema and RLS"| node_supabase
node_site_execution -->|"uploads images"| node_imagekit_service
node_imagekit_service -->|"requests auth"| node_imagekit_auth_function
node_imagekit_auth_function -->|"runs on"| node_supabase
node_imagekit_service -->|"uploads media"| node_imagekit
node_delivery -.->|"packages and deploys"| node_flutter_entry

click node_flutter_entry "https://github.com/najibcode/ibuild/blob/main/lib/main.dart"
click node_routing_shell "https://github.com/najibcode/ibuild/blob/main/lib/core/routing/router.dart"
click node_auth_controller "https://github.com/najibcode/ibuild/blob/main/lib/features/auth/presentation/controllers/auth_controller.dart"
click node_auth_repository "https://github.com/najibcode/ibuild/blob/main/lib/features/auth/data/repositories/auth_repository_impl.dart"
click node_permission_guard "https://github.com/najibcode/ibuild/blob/main/lib/features/rbac/presentation/widgets/permission_guard.dart"
click node_role_repository "https://github.com/najibcode/ibuild/blob/main/lib/features/rbac/data/repositories/supabase_role_repository.dart"
click node_projects "https://github.com/najibcode/ibuild/blob/main/lib/features/projects/presentation/screens/project_operations_screen.dart"
click node_project_controller "https://github.com/najibcode/ibuild/blob/main/lib/features/projects/presentation/controllers/project_controller.dart"
click node_project_repository "https://github.com/najibcode/ibuild/blob/main/lib/features/projects/data/repositories/supabase_project_repository.dart"
click node_workforce "https://github.com/najibcode/ibuild/blob/main/lib/features/attendance/presentation/controllers/attendance_controller.dart"
click node_site_execution "https://github.com/najibcode/ibuild/blob/main/lib/features/daily_progress/data/repositories/supabase_daily_progress_repository.dart"
click node_commercial "https://github.com/najibcode/ibuild/blob/main/lib/features/expenses/data/repositories/supabase_expense_repository.dart"
click node_inventory_equipment "https://github.com/najibcode/ibuild/blob/main/lib/features/inventory/data/repositories/supabase_inventory_repository.dart"
click node_export_services "https://github.com/najibcode/ibuild/blob/main/lib/core/services/generic_pdf_table_generator.dart"
click node_supabase_client "https://github.com/najibcode/ibuild/blob/main/lib/core/supabase/supabase_client.provider.dart"
click node_schema_migrations "https://github.com/najibcode/ibuild/blob/main/supabase/migrations/003_project_operations.sql"
click node_imagekit_service "https://github.com/najibcode/ibuild/blob/main/lib/services/imagekit/imagekit_service.dart"
click node_imagekit_auth_function "https://github.com/najibcode/ibuild/blob/main/supabase/functions/imagekit-auth/index.ts"
click node_delivery "https://github.com/najibcode/ibuild/blob/main/vercel.json"

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_flutter_entry,node_routing_shell toneBlue
class node_auth_controller,node_auth_repository,node_permission_guard,node_role_repository toneAmber
class node_projects,node_project_controller,node_project_repository,node_workforce,node_site_execution toneMint
class node_commercial,node_inventory_equipment,node_export_services toneRose
class node_supabase_client,node_supabase,node_schema_migrations,node_imagekit_service,node_imagekit_auth_function,node_imagekit,node_delivery toneIndigo
```

## Components

### Flutter Client

Multi-platform ERP runtime.

- [Flutter entry](https://github.com/najibcode/ibuild/blob/main/lib/main.dart): application entry · `lib/main.dart`
- [Routing & adaptive shell](https://github.com/najibcode/ibuild/blob/main/lib/core/routing/router.dart): navigation boundary · Selects mobile and web dashboard layouts. · `lib/core/routing/router.dart`

### Access Control

- [Auth controller](https://github.com/najibcode/ibuild/blob/main/lib/features/auth/presentation/controllers/auth_controller.dart): Riverpod controller · `lib/features/auth/presentation/controllers/auth_controller.dart`
- [Auth repository](https://github.com/najibcode/ibuild/blob/main/lib/features/auth/data/repositories/auth_repository_impl.dart): auth implementation · `lib/features/auth/data/repositories/auth_repository_impl.dart`
- [Permission guard](https://github.com/najibcode/ibuild/blob/main/lib/features/rbac/presentation/widgets/permission_guard.dart): UI authorization guard · `lib/features/rbac/presentation/widgets/permission_guard.dart`
- [Role repository](https://github.com/najibcode/ibuild/blob/main/lib/features/rbac/data/repositories/supabase_role_repository.dart): RBAC data repository · `lib/features/rbac/data/repositories/supabase_role_repository.dart`

### Operational Modules

- [Projects & operations](https://github.com/najibcode/ibuild/blob/main/lib/features/projects/presentation/screens/project_operations_screen.dart): central domain module · Provides the project/site context for operational records. · `lib/features/projects/presentation/screens/project_operations_screen.dart`
- [Project controller](https://github.com/najibcode/ibuild/blob/main/lib/features/projects/presentation/controllers/project_controller.dart): Riverpod controller · `lib/features/projects/presentation/controllers/project_controller.dart`
- [Project repository](https://github.com/najibcode/ibuild/blob/main/lib/features/projects/data/repositories/supabase_project_repository.dart): repository implementation · `lib/features/projects/data/repositories/supabase_project_repository.dart`
- [Workforce & attendance](https://github.com/najibcode/ibuild/blob/main/lib/features/attendance/presentation/controllers/attendance_controller.dart): operational module · Employees, attendance, wages, and attendance reports. · `lib/features/attendance/presentation/controllers/attendance_controller.dart`
- [Site execution](https://github.com/najibcode/ibuild/blob/main/lib/features/daily_progress/data/repositories/supabase_daily_progress_repository.dart): operational module · Progress, drawings, checklists, activities, and tickets. · `lib/features/daily_progress/data/repositories/supabase_daily_progress_repository.dart`

### Commercial & Assets

- [Finance & billing](https://github.com/najibcode/ibuild/blob/main/lib/features/expenses/data/repositories/supabase_expense_repository.dart): commercial module · Expenses, quotations, bills, payments, and ledgers. · `lib/features/expenses/data/repositories/supabase_expense_repository.dart`
- [Inventory & equipment](https://github.com/najibcode/ibuild/blob/main/lib/features/inventory/data/repositories/supabase_inventory_repository.dart): asset module · Stock history and fleet placement. · `lib/features/inventory/data/repositories/supabase_inventory_repository.dart`
- [PDF & Excel exports](https://github.com/najibcode/ibuild/blob/main/lib/core/services/generic_pdf_table_generator.dart): document service · `lib/core/services/generic_pdf_table_generator.dart`

### Platform Services

- [Supabase client boundary](https://github.com/najibcode/ibuild/blob/main/lib/core/supabase/supabase_client.provider.dart): backend integration · `lib/core/supabase/supabase_client.provider.dart`
- **Supabase**: system of record · PostgreSQL, Auth, RLS, storage, and Edge Functions.
- [SQL schema & policies](https://github.com/najibcode/ibuild/blob/main/supabase/migrations/003_project_operations.sql): database migrations · `supabase/migrations/003_project_operations.sql`
- [ImageKit media service](https://github.com/najibcode/ibuild/blob/main/lib/services/imagekit/imagekit_service.dart): media integration · `lib/services/imagekit/imagekit_service.dart`
- [ImageKit auth function](https://github.com/najibcode/ibuild/blob/main/supabase/functions/imagekit-auth/index.ts): Supabase Edge Function · Issues ImageKit authentication. · `supabase/functions/imagekit-auth/index.ts`
- **ImageKit**: media storage service
- [Web, native & CI delivery](https://github.com/najibcode/ibuild/blob/main/vercel.json): deployment infrastructure · Vercel SPA deployment, Android/iOS launchers, and GitHub Actions CI. · `vercel.json`

## Connections

- Flutter entry → Routing & adaptive shell: starts
- Routing & adaptive shell → Auth controller: auth flow
- Routing & adaptive shell → Projects & operations: navigates
- Routing & adaptive shell → Workforce & attendance: navigates
- Routing & adaptive shell → Site execution: navigates
- Routing & adaptive shell → Finance & billing: navigates
- Routing & adaptive shell → Inventory & equipment: navigates
- Auth controller → Auth repository: uses
- Auth repository → Supabase client boundary: auth API
- Permission guard → Role repository: checks permissions
- Role repository → Supabase client boundary: queries roles
- Projects & operations → Project controller: drives
- Project controller → Project repository: uses
- Project repository → Supabase client boundary: persists projects
- Workforce & attendance → Supabase client boundary: persists records
- Site execution → Supabase client boundary: persists evidence
- Finance & billing → Supabase client boundary: persists transactions
- Inventory & equipment → Supabase client boundary: persists assets
- Finance & billing → PDF & Excel exports: generates documents
- Supabase client boundary → Supabase: connects to
- SQL schema & policies → Supabase: defines schema and RLS
- Site execution → ImageKit media service: uploads images
- ImageKit media service → ImageKit auth function: requests auth
- ImageKit auth function → Supabase: runs on
- ImageKit media service → ImageKit: uploads media
- Web, native & CI delivery → Flutter entry: packages and deploys