# adjipratama99/directional-finder architecture

> Architecture diagram of the GitHub repository adjipratama99/directional-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adjipratama99/directional-finder
- Repository: https://github.com/adjipratama99/directional-finder

## Overview

##### Project type and purpose
- This is a full-stack Next.js 13 (app-router) application called “directional-finder.”
- Its main features include: user authentication (NextAuth), dashboards for directional finder data, inventory management, reporting, and user management.
- It exposes several internal REST API endpoints (under app/api/…) that talk to a database via a custom `db/` layer and ORM-style models.

##### File structure
Top-level directories and their roles:
- app/ – Next.js “app” router folder with:
– (sites) subfolder separating four main pages: dashboard, inventory, report, users
– Per-page UI components under each site folder
– API routes under app/api/… for auth, df (directional finder), inventory, report, satuan-wilayah, user
- components/ – shared React components and providers (ReactQueryClientProvider, SessionProvider, UI primitives, custom form/table/modal/etc.)
- db/ – database connection and CRUD/query-builder abstractions
- models/ – TypeScript model definitions matching database tables (SatuanKerja, user, inventory, etc.)
- redux/ – Redux Toolkit store and slices for client state
- hooks/ – custom React hooks (pagination, export, debounce, etc.)
- lib/ – utilities (Fetcher HTTP client, authOptions for NextAuth, misc utils)
- public/uploads – runtime file storage for PDFs
- context/ – React Context (MenuContext)
- config & root files – next.config.ts, middleware.ts, package.json, tsconfig.json

##### README
- Only covers installation, build, and start commands; does not include an architecture section.
- We infer from code that it runs as a Node/Next.js server, renders both server and client components, and uses API routes to power front-end data.

a. Main components:
- Client (browser) – React/Next.js front-end code, served by Next.js
- Next.js Server – handles SSR/SSG/page rendering and API endpoints
- NextAuth Module – under app/api/auth, handles session and JWT, integrates with SessionProvider on client
- Database – SQL (e.g., PostgreSQL/MySQL) accessed via db/connect.ts, repository.ts, crud.ts, and models in models/
- File Storage – local disk (public/uploads) for PDFs; could be swapped for S3
- External Services – OAuth providers (implicit in NextAuth), email or logging services if used

b. Relationships and data flow:
1. User → Next.js frontend (page.tsx under app/)
2. Frontend components → ReactQueryClientProvider or Redux hooks → call internal API endpoints (Fetcher.ts)
3. API route handlers (e.g., app/api/inventory/route.ts) → use `db/` layer to query/update database
4. db layer → database → returns results → API route returns JSON → ReactQuery updates UI
5. File upload endpoints (if any) write to public/uploads folder → served statically via Next.js public folder
6. NextAuth routes → manage login, session, store tokens/cookies

c. Architectural patterns & design principles
- Separation of concerns: UI components vs. data-fetching hooks vs. API routes vs. database layer
- Next.js “app” router pattern: nested layouts, server and client components
- Custom hook pattern for pagination, export, debounce
- Repository/Builder pattern in db/queryBuilder + repo.ts
- Centralized state with Redux + React Query for caching and server-state management
- Context for global UI state (menu open/closed)

d. Key technologies & frameworks
- Frontend: Next.js 13 (app router), React 18, TypeScript
- Styling: Tailwind CSS (globals.css + postcss.config.mjs)
- State & data: Redux Toolkit, React Query
- Authentication: NextAuth.js
- Database: Node.js with custom query builder (likely on top of MySQL/Postgres)
- Build & deployment: Node.js server, `npm run build && npm run start`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Browser)" 
        direction TB
        Browser["User Browser"]:::external
        Browser -->|"Renders UI"| Providers
        subgraph "Providers & Layout" 
            direction TB
            Providers["ReactQueryClientProvider\nSessionProvider"]:::frontend
            Navbar["Navbar"]:::frontend
            Providers --> Navbar
            click Providers "https://github.com/adjipratama99/directional-finder/blob/main/components/ReactQueryClientProvider.tsx"
            click Providers "https://github.com/adjipratama99/directional-finder/blob/main/components/SessionProvider.tsx"
            click Navbar "https://github.com/adjipratama99/directional-finder/blob/main/components/layouts/navbar.tsx"
        end
        Navbar --> Pages
    end

    subgraph "Pages (Next.js App Router)" 
        direction TB
        DashPage["Dashboard Page"]:::frontend
        InvPage["Inventory Page"]:::frontend
        RepPage["Report Page"]:::frontend
        UserPage["Users Page"]:::frontend

        DashPage -->|uses| CardDF
        DashPage -->|uses| ModalReqDF
        InvPage -->|uses| CardInv
        InvPage -->|uses| ColumnsInv
        InvPage -->|uses| FilterInv
        InvPage -->|uses| ModalAddItem
        RepPage -->|uses| ModalSetType
        UserPage -->|uses| ColumnsUser
        UserPage -->|uses| ModalAddUser

        click DashPage "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/dashboard/page.tsx"
        click InvPage "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/inventory/page.tsx"
        click RepPage "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/report/page.tsx"
        click UserPage "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/users/page.tsx"

        click CardDF "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/dashboard/_components/card-df.tsx"
        click ModalReqDF "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/dashboard/_components/modal-request-df.tsx"
        click CardInv "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/inventory/_components/card-inventory.tsx"
        click ColumnsInv "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/inventory/_components/columns.tsx"
        click FilterInv "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/inventory/_components/filter-*.tsx"
        click ModalAddItem "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/inventory/_components/modal-add-item.tsx"
        click ModalSetType "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/report/_components/modal-set-type-data.tsx"
        click ColumnsUser "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/users/_components/columns.tsx"
        click ModalAddUser "https://github.com/adjipratama99/directional-finder/blob/main/app/(sites)/users/_components/modal-add-user.tsx"
    end

    Providers --> Pages
    Pages -->|calls via Fetcher| API

    %% API Layer
    subgraph "Next.js Server (API Routes)" 
        direction TB
        AuthAPI["Auth API Route"]:::api
        DFAPI["DF API Route"]:::api
        InvAPI["Inventory API Route"]:::api
        RepAPI["Report API Route"]:::api
        SWAPI["Satuan Wilayah API Route"]:::api
        UserAPI["User API Route"]:::api

        AuthAPI -->|handles login| NextAuthMod
        DFAPI -->|CRUD| DbLayer
        InvAPI -->|CRUD| DbLayer
        RepAPI -->|CRUD| DbLayer
        SWAPI -->|CRUD| DbLayer
        UserAPI -->|CRUD| DbLayer

        click AuthAPI "https://github.com/adjipratama99/directional-finder/blob/main/app/api/auth/[...nextauth]/route.ts"
        click DFAPI "https://github.com/adjipratama99/directional-finder/blob/main/app/api/df/route.ts"
        click InvAPI "https://github.com/adjipratama99/directional-finder/blob/main/app/api/inventory/route.ts"
        click RepAPI "https://github.com/adjipratama99/directional-finder/blob/main/app/api/report/route.ts"
        click SWAPI "https://github.com/adjipratama99/directional-finder/blob/main/app/api/satuan-wilayah/route.ts"
        click UserAPI "https://github.com/adjipratama99/directional-finder/blob/main/app/api/user/route.ts"
    end

    API["API Call"]:::frontend --> AuthAPI
    API --> DFAPI
    API --> InvAPI
    API --> RepAPI
    API --> SWAPI
    API --> UserAPI

    %% NextAuth Module
    subgraph "NextAuth Module" 
        direction TB
        NextAuthMod["NextAuth Handler"]:::external
        NextAuthMod -->|uses| AuthOptions
        click AuthOptions "https://github.com/adjipratama99/directional-finder/blob/main/lib/authOptions.ts"
    end

    %% Database Layer
    subgraph "Database Layer" 
        direction TB
        Connect["db/connect.ts"]:::db
        QB["db/queryBuilder.ts"]:::db
        CRUD["db/crud.ts"]:::db
        Repo["db/repository.ts"]:::db
        Handler["db/handler.ts"]:::db

        Connect --> QB --> CRUD --> Repo --> Handler
        Handler --> Database
        click Connect "https://github.com/adjipratama99/directional-finder/blob/main/db/connect.ts"
        click QB "https://github.com/adjipratama99/directional-finder/blob/main/db/queryBuilder.ts"
        click CRUD "https://github.com/adjipratama99/directional-finder/blob/main/db/crud.ts"
        click Repo "https://github.com/adjipratama99/directional-finder/blob/main/db/repository.ts"
        click Handler "https://github.com/adjipratama99/directional-finder/blob/main/db/handler.ts"
    end

    %% Models
    subgraph "ORM Models" 
        direction TB
        DFModel["directionalFinder.model.ts"]:::db
        InvModel["inventory.model.ts"]:::db
        SKModel["SatuanKerja.model.ts"]:::db
        UPModel["uploadedFiles.model.ts"]:::db
        UserModel["user.model.ts"]:::db

        click DFModel "https://github.com/adjipratama99/directional-finder/blob/main/models/directionalFinder.model.ts"
        click InvModel "https://github.com/adjipratama99/directional-finder/blob/main/models/inventory.model.ts"
        click SKModel "https://github.com/adjipratama99/directional-finder/blob/main/models/SatuanKerja.model.ts"
        click UPModel "https://github.com/adjipratama99/directional-finder/blob/main/models/uploadedFiles.model.ts"
        click UserModel "https://github.com/adjipratama99/directional-finder/blob/main/models/user.model.ts"
    end

    Handler --> DFModel
    Handler --> InvModel
    Handler --> SKModel
    Handler --> UPModel
    Handler --> UserModel

    %% Storage and External
    Database[(Database)]:::storage
    FileStorage["public/uploads (File Storage)"]:::storage
    InvAPI -->|uploads files| FileStorage
    FileStorage -->|served statically| Browser

    %% Utilities & Config
    subgraph "Utilities & Config" 
        direction TB
        Fetcher["lib/Fetcher.ts"]:::db
        Utils["lib/utils.ts"]:::db
        Messages["lib/messages.ts"]:::db
        Middleware["middleware.ts"]:::db
        NextConf["next.config.ts"]:::db
        PostCSS["postcss.config.mjs"]:::db

        click Fetcher "https://github.com/adjipratama99/directional-finder/blob/main/lib/Fetcher.ts"
        click Utils "https://github.com/adjipratama99/directional-finder/blob/main/lib/utils.ts"
        click Messages "https://github.com/adjipratama99/directional-finder/blob/main/lib/messages.ts"
        click Middleware "https://github.com/adjipratama99/directional-finder/blob/main/middleware.ts"
        click NextConf "https://github.com/adjipratama99/directional-finder/blob/main/next.config.ts"
        click PostCSS "https://github.com/adjipratama99/directional-finder/blob/main/postcss.config.mjs"
    end

    %% Styles
    classDef frontend fill:#E6F7FF,stroke:#333,stroke-width:1px
    classDef api fill:#E6FFE6,stroke:#333,stroke-width:1px
    classDef db fill:#FFF9E6,stroke:#333,stroke-width:1px
    classDef storage fill:#FFF0E6,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px
```
