rdeeanz/pelindo-mafp

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.