# nubplayz/metrofinder-lost-items architecture

> Architecture diagram of the GitHub repository nubplayz/metrofinder-lost-items, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nubplayz/metrofinder-lost-items
- Repository: https://github.com/nubplayz/metrofinder-lost-items

## Overview

##### Project type and purpose
- This is a full-stack React/Next.js web application created with `create-next-app`.
- The “app” directory holds both the frontend UI (pages, layouts, styles) and serverless API routes (`app/api/items/route.ts`).
- There is also a side “script” folder containing Node.js data-processing scripts and a JSON file (`allItems.json`), plus a small “liberary” module for filtering logic.

##### File structure
- Top-level directories:
- app/ – Next.js App Router: UI pages (`page.tsx`), layout (`layout.tsx`), global styles, and API routes.
- liberary/ – Shared filtering utilities (filter.ts, linefilter.ts).
- script/ – Separate Node.js scripts for data preparation and JSON output.
- Config files:
- next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs
- package.json/package-lock.json for dependencies
- No external database directory: data is read from local JSON (`script/allItems.json`) or computed via library functions.

##### README
- Confirms use of Next.js with App Router, server-side rendering and API routes.
- Mentions no built-in backend database—likely static or file-based data.
- Deployment target is Vercel (serverless).

##### Main components and their interactions
a. Browser (Client)
- Sends HTTP requests to Next.js for both page loads (SSR/CSR) and API calls (`/api/items`).
- Renders React components defined in `app/page.tsx` and sub-components.
b. Next.js Server (Serverless Functions on Vercel)
- SSR Entry points (the React pages)
- API route handler at `app/api/items/route.ts`
- Reads / transforms data via the “liberary” module.
c. liberary Module (Business Logic)
- Pure TS functions (`filter.ts`, `linefilter.ts`) that apply domain-specific filters to raw data.
- Called by both the API route and potentially by page code (if some filtering is done client-side).
d. Data Source
- Static JSON (`script/allItems.json`), generated by Node scripts for initial data.
- Node scripts (`script/index1.js`, `uniqueStation.js`) run offline or at build time to produce or clean data.
e. Build & Deployment
- Next.js build process (via next.config.ts, PostCSS, TypeScript)
- Hosted on Vercel or comparable platform.

##### Architectural patterns and design principles
- File-system routing (App Router) for pages & API routes.
- Separation of concerns:
- Presentation layer in `app/`
- Business logic in `liberary/`
- Data ingestion in `script/`
- Serverless, zero-server infrastructure: each API file becomes an AWS Lambda (or Vercel Function).
- Static assets decoupled under `public/`.

1. Client (Browser)
2. Next.js Frontend (Page components, SSR)
3. Next.js Backend (API Route)
4. Business Logic Module (liberary)
5. Data Source (JSON files, script outputs)
- From Client → Frontend (HTTP GET/POST)
- From Client → API route (fetch to `/api/items`)
- From API route → liberary functions (function calls/imports)
- From liberary → Data Source (read file or memory)
- Blue rectangles for user-facing components (Browser, React pages)
- Green rectangles for server-side components (API route, business logic)

- Clear labels for all components and directories.
- UI layer
- API layer
- Business-logic layer
- Data layer
- Build/configuration artifacts

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Browser["Browser\n(Client)"]:::frontend
    end

    subgraph "Frontend Layer (Next.js)"
        Page["app/page.tsx"]:::frontend
        Layout["app/layout.tsx"]:::frontend
        Styles["app/globals.css"]:::frontend
    end

    subgraph "Backend Layer (API)"
        API["app/api/items/route.ts\n(API Route)"]:::backend
    end

    subgraph "Business Logic (liberary)"
        Filter["liberary/filter.ts"]:::logic
        LineFilter["liberary/linefilter.ts"]:::logic
    end

    subgraph "Data Source"
        JSON["script/allItems.json"]:::data
    end

    subgraph "ETL Scripts (Offline)"
        Index["script/index1.js"]:::etl
        Unique["script/uniqueStation.js"]:::etl
    end

    subgraph "Build & Config"
        NC["next.config.ts"]:::config
        TS["tsconfig.json"]:::config
        PostCSS["postcss.config.mjs"]:::config
        ESLint["eslint.config.mjs"]:::config
    end

    %% Relationships
    Browser -->|"Initial page load (SSR)"| Page
    Page -->|"Hydrate (CSR)"| Browser
    Browser -->|"fetch /api/items (CSR)"| API
    API -->|"calls" | Filter
    API -->|"calls" | LineFilter
    Filter -->|"reads" | JSON
    LineFilter -->|"reads" | JSON
    JSON -->|"data" | API
    Index -->|"generates JSON" | JSON
    Unique -->|"generates/cleans JSON" | JSON
    NC -->|build config| Page
    NC -->|build config| API

    %% Click Events
    click Page "https://github.com/nubplayz/metrofinder-lost-items/blob/master/app/page.tsx"
    click Layout "https://github.com/nubplayz/metrofinder-lost-items/blob/master/app/layout.tsx"
    click Styles "https://github.com/nubplayz/metrofinder-lost-items/blob/master/app/globals.css"
    click API "https://github.com/nubplayz/metrofinder-lost-items/blob/master/app/api/items/route.ts"
    click Filter "https://github.com/nubplayz/metrofinder-lost-items/blob/master/liberary/filter.ts"
    click LineFilter "https://github.com/nubplayz/metrofinder-lost-items/blob/master/liberary/linefilter.ts"
    click JSON "https://github.com/nubplayz/metrofinder-lost-items/blob/master/script/allItems.json"
    click Index "https://github.com/nubplayz/metrofinder-lost-items/blob/master/script/index1.js"
    click Unique "https://github.com/nubplayz/metrofinder-lost-items/blob/master/script/uniqueStation.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#DFFFD0,stroke:#28a745,stroke-width:1px;
    classDef logic fill:#E8FFE8,stroke:#22863a,stroke-width:1px;
    classDef data fill:#E8E8E8,stroke:#6a737d,stroke-width:1px,stroke-dasharray: 4 2;
    classDef etl fill:#FFE8D0,stroke:#d73a49,stroke-width:1px;
    classDef config fill:#F0F0F0,stroke:#999999,stroke-width:1px,stroke-dasharray: 2 2;
```
