# rdeeanz/pelindo-mafp architecture

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

- Interactive diagram: https://gitdiagram.com/rdeeanz/pelindo-mafp
- Repository: https://github.com/rdeeanz/pelindo-mafp

## Overview

1. **Overall shape**
   - This is a **Next.js 15 App Router** application built to run on **Cloudflare Pages/Workers** with the **edge runtime**.
   - The repo is split cleanly into **route handlers/UI in `src/app`**, **domain logic in `src/lib`**, **presentational components in `src/components`**, and **D1 migrations in `migrations/`**.

2. **Primary user-facing routes**
   - The app is organized around a small set of business pages: **dashboard**, **branch list/detail/edit**, **regional recap**, **settings**, and **login**.
   - Route groups separate **authenticated app pages** under `src/app/(app)` from the **auth page** under `src/app/(auth)`, which is a useful boundary for diagramming access-controlled areas.

3. **Authentication and session boundary**
   - Authentication is **JWT-based** and stored in an **httpOnly cookie**.
   - The auth subsystem in `src/lib/auth` includes password hashing, JWT creation/verification, role logic, authorization checks, and session helpers.
   - `middleware.ts` is the likely gatekeeper for protecting app routes and steering unauthenticated users to `/login`.

4. **Data persistence**
   - The backend database is **Cloudflare D1 (SQLite)**, accessed through `src/lib/db.ts`.
   - Schema changes are managed with SQL migrations:
     - `0001_init.sql` for base tables
     - `0002_seed.sql` for initial seed data
     - `0003_superadmin_settings.sql` for later admin/configuration expansion
   - This makes D1 the central system of record for branches, users, facilities, monitoring records, and configuration.

5. **Domain model and queries**
   - The `src/lib/queries` layer is the main read/write boundary over the database, separated by domain:
     - `branches.ts`
     - `facilities.ts`
     - `monitoring.ts`
     - `settings.ts`
     - `users.ts`
   - This suggests a service-style architecture where routes/components call query modules instead of embedding SQL directly.

6. **Monitoring workflow**
   - The core business flow is collecting and maintaining **facility availability monitoring** for branch ports.
   - The edit page for a branch, plus components like `MonitoringForm`, `ObjectRowInput`, and `FacilityMetaEditor`, indicate a structured input flow for facility availability values and metadata.
   - `src/lib/report/buildReport.ts` and `recomputeReport.ts` show that monitoring changes feed a derived reporting layer, so the system stores raw monitoring data and also computes report views from it.

7. **Reporting and analytics views**
   - The dashboard (`/dashboard`) presents **regional summary cards** and **branch availability bars**.
   - The branch detail page (`/branches/[branchId]`) shows a **Lap. Cabang** report table, and the recap page (`/recap`) shows a **regional recap table**.
   - These views rely on shared table/report logic in `src/components/table` and `src/lib/utils` for period handling, availability calculations, and formatting.

8. **Administration and settings**
   - The settings area is a separate admin subsystem with subpages for **branches, categories, facilities, users, and website settings**.
   - Each settings domain has both UI panels and API routes under `src/app/api/settings/...`, which implies CRUD-style management of master data and configuration.
   - The presence of `SuperadminPanel` and role-aware auth logic suggests differentiated access between **regional admins** and **branch PIC users**.

9. **API surface**
   - The app uses route handlers in `src/app/api` as its server boundary:
     - `/api/auth/login`, `/logout`, `/me`
     - `/api/branches`
     - `/api/facilities` and `/api/facilities/reorder`
     - `/api/settings/...`
     - `/api/monitoring`
   - In architecture terms, browser UI talks to these handlers for authentication, CRUD actions, and monitoring updates; the handlers in turn talk to D1 and domain logic.

10. **Excel export pipeline**
   - Export is a first-class feature, not an afterthought.
   - `src/lib/export/generateLapCabangXlsx.ts` and `generateRekapXlsx.ts` produce `.xlsx` files using **xlsx-js-style**, and there is a dedicated template file in the repo root.
   - Export buttons in `src/components/export` indicate that users can generate reports directly from the browser, matching an existing business Excel format.

11. **Shared UI and layout composition**
   - The app shell is composed from `AppShell`, `Sidebar`, `Navbar`, `ThemeToggle`, and reusable UI primitives like `Button`, `Card`, `Input`, `Select`, `Badge`, and `Toast`.
   - This means most pages are built by combining a common authenticated layout with page-specific panels/tables rather than each page managing its own chrome.

12. **Important cross-cutting utilities**
   - `src/lib/utils` contains availability math, date/period parsing, formatter helpers, and settings filters.
   - `src/lib/constants.ts`, `src/types`, and `src/lib/navigation.ts` act as shared contracts that reduce duplication across dashboard, tables, forms, and API handlers.

13. **Operational/runtime constraints**
   - The app is designed around **Cloudflare-specific deployment**: Pages build output, D1 binding, and environment secrets via Wrangler.
   - This affects the architecture because server code must be compatible with the edge runtime and uses Cloudflare bindings rather than a traditional Node backend.

14. **High-level request/data flow**
   - A typical flow is: user logs in → JWT cookie is issued → middleware allows access → page loads and calls query/API layers → D1 returns branch/facility/monitoring data → UI renders tables/cards → optionally export generators turn the same data into Excel.
   - For an architecture diagram, the key boundaries are **browser UI**, **Next.js route handlers / edge runtime**, **auth/session layer**, **query/report/export business logic**, and **Cloudflare D1 storage**.

Main entry points: [`src/lib/report/buildReport.ts`](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/report/buildReport.ts) (Report Engine), [`src/lib/db.ts`](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/db.ts) (D1 Access), [`src/app/(app)/dashboard/page.tsx`](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/dashboard/page.tsx) (Dashboard), [`src/app/api/auth/login/route.ts`](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/auth/login/route.ts) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_src_app_layout["Root Layout<br/>next layout<br/>[layout.tsx]"]
  node_src_app_app_layout["App Shell<br/>route layout<br/>[layout.tsx]"]
  node_src_app_login["Login<br/>auth page<br/>[page.tsx]"]
  node_src_app_dashboard["Dashboard<br/>app page<br/>[page.tsx]"]
  node_src_app_branches["Branches<br/>app page<br/>[page.tsx]"]
  node_src_app_branch_detail["Branch Detail<br/>app page<br/>[page.tsx]"]
  node_src_app_branch_edit["Edit Branch<br/>app page<br/>[page.tsx]"]
  node_src_app_recap["Recap<br/>app page<br/>[page.tsx]"]
  node_src_app_settings["Settings<br/>admin page<br/>[page.tsx]"]
  node_src_app_api_auth["Auth API<br/>route handlers<br/>[route.ts]"]
  node_src_app_api_branches["Branches API<br/>route handlers<br/>[route.ts]"]
  node_src_app_api_monitoring["Monitoring API<br/>route handlers<br/>[route.ts]"]
  node_src_app_api_settings["Settings API<br/>route handlers<br/>[route.ts]"]
end

subgraph group_components["UI Components"]
  node_src_components_shell["App Shell UI<br/>layout components<br/>[AppShell.tsx]"]
  node_src_components_dashboard["Dashboard Cards<br/>dashboard components<br/>[SummaryCard.tsx]"]
  node_src_components_branch_report["Report Panel<br/>table components"]
  node_src_components_monitoring_form["Monitoring Form<br/>form components<br/>[MonitoringForm.tsx]"]
  node_src_components_export["Excel Export<br/>export components"]
end

subgraph group_lib["Domain Logic"]
  node_src_lib_auth["Auth Session<br/>auth core<br/>[session.ts]"]
  node_src_lib_queries["Query Layer<br/>data access<br/>[branches.ts]"]
  node_src_lib_report["Report Engine<br/>reporting<br/>[buildReport.ts]"]
  node_src_lib_export["XLSX Export<br/>export engine"]
  node_src_lib_db[("D1 Access<br/>database adapter<br/>[db.ts]")]
end

subgraph group_data["Data Layer"]
  node_migrations_0001["Init Schema<br/>migration sql<br/>[0001_init.sql]"]
end

node_src_app_layout -->|"wraps"| node_src_app_app_layout
node_src_app_layout -->|"serves"| node_src_app_login
node_src_app_app_layout -->|"uses"| node_src_components_shell
node_src_app_login -->|"posts to"| node_src_app_api_auth
node_src_app_api_auth -->|"uses"| node_src_lib_auth
node_src_app_api_auth -->|"reads"| node_src_lib_db
node_src_app_dashboard -->|"renders"| node_src_components_dashboard
node_src_app_dashboard -->|"loads"| node_src_app_api_branches
node_src_app_branches -->|"loads"| node_src_app_api_branches
node_src_app_branch_detail -->|"renders"| node_src_components_branch_report
node_src_app_branch_detail -->|"computes"| node_src_lib_report
node_src_app_branch_edit -->|"renders"| node_src_components_monitoring_form
node_src_app_branch_edit -->|"writes to"| node_src_app_api_monitoring
node_src_app_recap -->|"reads"| node_src_lib_report
node_src_app_settings -->|"manages"| node_src_app_api_settings
node_src_app_dashboard -->|"exports"| node_src_components_export
node_src_app_recap -->|"exports"| node_src_components_export
node_src_components_export -->|"calls"| node_src_lib_export
node_src_lib_queries -->|"queries"| node_src_lib_db
node_src_lib_report -->|"uses"| node_src_lib_queries
node_src_lib_export -->|"formats"| node_src_lib_report
node_src_lib_auth -->|"checks"| node_src_lib_db
node_src_lib_db -->|"defined by"| node_migrations_0001

click node_src_app_layout "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/layout.tsx"
click node_src_app_app_layout "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/layout.tsx"
click node_src_app_login "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(auth)/login/page.tsx"
click node_src_app_dashboard "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/dashboard/page.tsx"
click node_src_app_branches "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/branches/page.tsx"
click node_src_app_branch_detail "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/branches/[branchId]/page.tsx"
click node_src_app_branch_edit "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/branches/[branchId]/edit/page.tsx"
click node_src_app_recap "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/recap/page.tsx"
click node_src_app_settings "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/settings/page.tsx"
click node_src_app_api_auth "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/auth/login/route.ts"
click node_src_app_api_branches "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/branches/route.ts"
click node_src_app_api_monitoring "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/monitoring/route.ts"
click node_src_app_api_settings "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/settings/branches/route.ts"
click node_src_components_shell "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/layout/AppShell.tsx"
click node_src_components_dashboard "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/dashboard/SummaryCard.tsx"
click node_src_components_branch_report "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/table/BranchReportPanel.tsx"
click node_src_components_monitoring_form "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/form/MonitoringForm.tsx"
click node_src_components_export "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/export/DownloadExcelButton.tsx"
click node_src_lib_auth "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/auth/session.ts"
click node_src_lib_queries "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/queries/branches.ts"
click node_src_lib_report "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/report/buildReport.ts"
click node_src_lib_export "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/export/generateLapCabangXlsx.ts"
click node_src_lib_db "https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/db.ts"
click node_migrations_0001 "https://github.com/rdeeanz/pelindo-mafp/blob/main/migrations/0001_init.sql"

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_src_app_layout,node_src_app_app_layout,node_src_app_login,node_src_app_dashboard,node_src_app_branches,node_src_app_branch_detail,node_src_app_branch_edit,node_src_app_recap,node_src_app_settings,node_src_app_api_auth,node_src_app_api_branches,node_src_app_api_monitoring,node_src_app_api_settings toneBlue
class node_src_components_shell,node_src_components_dashboard,node_src_components_branch_report,node_src_components_monitoring_form,node_src_components_export toneAmber
class node_src_lib_auth,node_src_lib_queries,node_src_lib_report,node_src_lib_export,node_src_lib_db toneMint
class node_migrations_0001 toneRose
```

## Components

### App Router

Next.js route groups, pages, and API handlers

- [Root Layout](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/layout.tsx): next layout · Global app wrapper and document shell · `src/app/layout.tsx`
- [App Shell](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/layout.tsx): route layout · Authenticated application layout boundary · `src/app/(app)/layout.tsx`
- [Login](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(auth)/login/page.tsx): auth page · Public sign-in page · `src/app/(auth)/login/page.tsx`
- [Dashboard](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/dashboard/page.tsx): app page · Regional summary and availability overview · `src/app/(app)/dashboard/page.tsx`
- [Branches](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/branches/page.tsx): app page · Branch list and navigation hub · `src/app/(app)/branches/page.tsx`
- [Branch Detail](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/branches/[branchId]/page.tsx): app page · Per-branch report view · `src/app/(app)/branches/[branchId]/page.tsx`
- [Edit Branch](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/branches/[branchId]/edit/page.tsx): app page · Monitoring and facility editing flow · `src/app/(app)/branches/[branchId]/edit/page.tsx`
- [Recap](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/recap/page.tsx): app page · Regional recap table view · `src/app/(app)/recap/page.tsx`
- [Settings](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/(app)/settings/page.tsx): admin page · Settings hub for master data and configuration · `src/app/(app)/settings/page.tsx`
- [Auth API](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/auth/login/route.ts): route handlers · Login, logout, and session endpoints · `src/app/api/auth/login/route.ts`
- [Branches API](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/branches/route.ts): route handlers · Branch data endpoint · `src/app/api/branches/route.ts`
- [Monitoring API](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/monitoring/route.ts): route handlers · Monitoring update endpoint · `src/app/api/monitoring/route.ts`
- [Settings API](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/app/api/settings/branches/route.ts): route handlers · CRUD endpoints for admin master data · `src/app/api/settings/branches/route.ts`

### UI Components

Shared layout, form, table, dashboard, and export UI

- [App Shell UI](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/layout/AppShell.tsx): layout components · Sidebar, navbar, theme toggle, and page chrome · `src/components/layout/AppShell.tsx`
- [Dashboard Cards](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/dashboard/SummaryCard.tsx): dashboard components · Summary and availability presentation · `src/components/dashboard/SummaryCard.tsx`
- [Report Panel](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/table/BranchReportPanel.tsx): table components · Branch report table and period controls · `src/components/table/BranchReportPanel.tsx`
- [Monitoring Form](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/form/MonitoringForm.tsx): form components · Branch monitoring editor and row inputs · `src/components/form/MonitoringForm.tsx`
- [Excel Export](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/components/export/DownloadExcelButton.tsx): export components · Download buttons for report exports · `src/components/export/DownloadExcelButton.tsx`

### Domain Logic

Auth, queries, reporting, export, and shared utilities

- [Auth Session](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/auth/session.ts): auth core · JWT, password, role, and authorization helpers · `src/lib/auth/session.ts`
- [Query Layer](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/queries/branches.ts): data access · Branch, facility, monitoring, settings, and user queries · `src/lib/queries/branches.ts`
- [Report Engine](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/report/buildReport.ts): reporting · Report building and recomputation logic · `src/lib/report/buildReport.ts`
- [XLSX Export](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/export/generateLapCabangXlsx.ts): export engine · Excel generation for Lap. Cabang and Rekap · `src/lib/export/generateLapCabangXlsx.ts`
- [D1 Access](https://github.com/rdeeanz/pelindo-mafp/blob/main/src/lib/db.ts): database adapter · Cloudflare D1 connection boundary · `src/lib/db.ts`

### Data Layer

Cloudflare D1 schema and migrations

- [Init Schema](https://github.com/rdeeanz/pelindo-mafp/blob/main/migrations/0001_init.sql): migration sql · Base tables and schema foundation · `migrations/0001_init.sql`

## Connections

- Root Layout → App Shell: wraps · Root layout composes the authenticated app shell and public routes
- Root Layout → Login: serves · Public auth page sits under the root app layout
- App Shell → App Shell UI: uses · Authenticated route group renders the shared shell
- Login → Auth API: posts to · Login form authenticates through route handlers
- Auth API → Auth Session: uses · Auth endpoints issue and verify sessions
- Auth API → D1 Access: reads · Login and session handlers consult stored users
- Dashboard → Dashboard Cards: renders · Dashboard page is built from summary and availability widgets
- Dashboard → Branches API: loads · Dashboard consumes branch data through server endpoints
- Branches → Branches API: loads · Branch list page reads branch records
- Branch Detail → Report Panel: renders · Detail page centers on branch report presentation
- Branch Detail → Report Engine: computes · Report view relies on derived report building
- Edit Branch → Monitoring Form: renders · Edit page uses the monitoring input workflow
- Edit Branch → Monitoring API: writes to · Monitoring form submits updates through the API
- Recap → Report Engine: reads · Recap page consumes derived reporting data
- Settings → Settings API: manages · Settings pages use CRUD endpoints for master data
- Dashboard → Excel Export: exports · Dashboard and reporting views offer Excel download actions
- Recap → Excel Export: exports · Recap page can generate spreadsheet output
- Excel Export → XLSX Export: calls · UI export actions invoke XLSX generators
- Query Layer → D1 Access: queries · Domain queries are the main database access layer
- Report Engine → Query Layer: uses · Report computation reads domain data from queries
- XLSX Export → Report Engine: formats · Export generation reuses report data and calculations
- Auth Session → D1 Access: checks · Session and authorization logic depend on persisted users and roles
- D1 Access → Init Schema: defined by · D1 schema originates from migrations