# sooluh/kodepos architecture

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

- Interactive diagram: https://gitdiagram.com/sooluh/kodepos
- Repository: https://github.com/sooluh/kodepos

## Overview

##### Main Components

a) API Layer
- REST API endpoints (/search and /detect)
- Fastify server framework (evident from types/fastify)

b) Controller Layer
- Search Controller
- Detect Controller
- Home Controller

c) Data Layer
- Static JSON Data Store (data/kodepos.json)

d) Helper Layer
- Kodepos Helper
- Specification Helper

**┌─────────────────────────────────────────────────────┐**
- Client Requests                    │
- ┬─────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────┐**
- API Gateway                       │
- (Vercel/Koyeb/Render Deployment)          │
- ┬─────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────┐**
- Fastify Server                      │
- ┌───────────────┬──────────────┬───────────┐    │
- Routes     │    Core      │   Types   │    │
- ┬───────┴──────────────┴───────────┘    │
- ┼───────────────────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────┐**
- Controllers                        │
- ┌──────────┐    ┌─────────┐    ┌──────────┐      │
- Search  │    │ Detect  │    │   Home   │      │
- ┬─────┘    └────┬────┘    └────┬─────┘      │
- ┼───────────────┼───────────────┼────────────┘

- ↓               ↓               ↓
**┌─────────────────────────────────────────────────────┐**
- Helpers                          │
- ┌────────────┐    ┌─────────────┐           │
- Kodepos  │    │    Spec     │           │
- ┬──────┘    └──────┬──────┘           │
- ┼─────────────────┬┼─────────────────┘

- ↓                  ↓│
**┌─────────────────────────────────────────────────────┐**
- Data Store                         │
- (kodepos.json)                         │
- ┘

##### Important Elements to Highlight

a) Request Flow:
- How requests flow from client through API gateway
- Routing to appropriate controllers
- Demonstrate data access patterns

b) Deployment Options:
- Supported deployment platforms (Vercel, Koyeb, Render)
- How they interact with the core application

c) Data Flow:
- How search queries are processed
- How coordinate-based detection works
- Demonstrate response formatting

##### Technical Details

- Node.js runtime requirement (>= 20.x)
- TypeScript compilation flow
- Development vs Production modes
- Static file serving mechanism

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client ["Client Layer"]
        CR[Client Requests]
    end

    subgraph Gateway ["API Gateway Layer"]
        AG["API Gateway"]
        VER["Vercel"]:::deploy
        KOY["Koyeb"]:::deploy
        REN["Render"]:::deploy
        AG --> VER & KOY & REN
    end

    subgraph Server ["Server Layer"]
        FS["Fastify Server"]:::server
        RT["Routes"]:::core
        CORE["Core"]:::core
        TYP["Types"]:::types
        FS --> RT & CORE & TYP
    end

    subgraph Controllers ["Controller Layer"]
        SC["Search Controller"]:::controller
        DC["Detect Controller"]:::controller
        HC["Home Controller"]:::controller
    end

    subgraph Helpers ["Helper Layer"]
        KH["Kodepos Helper"]:::helper
        SH["Spec Helper"]:::helper
    end

    subgraph Data ["Data Layer"]
        DS["Static JSON Data Store"]:::data
    end

    %% Flow connections
    CR --> AG
    Gateway --> FS
    RT --> SC & DC & HC
    SC & DC & HC --> KH & SH
    KH & SH --> DS

    %% Styling
    classDef deploy fill:#1E88E5,color:white
    classDef server fill:#43A047,color:white
    classDef core fill:#004D40,color:white
    classDef types fill:#6D4C41,color:white
    classDef controller fill:#FF7043,color:white
    classDef helper fill:#FDD835,color:black
    classDef data fill:#7E57C2,color:white

    %% Click events
    click FS "https://github.com/sooluh/kodepos/blob/main/start/core.ts"
    click RT "https://github.com/sooluh/kodepos/blob/main/start/routes.ts"
    click TYP "https://github.com/sooluh/kodepos/blob/main/types/fastify/index.d.ts"
    click SC "https://github.com/sooluh/kodepos/blob/main/app/controllers/search.ts"
    click DC "https://github.com/sooluh/kodepos/blob/main/app/controllers/detect.ts"
    click HC "https://github.com/sooluh/kodepos/blob/main/app/controllers/home.ts"
    click KH "https://github.com/sooluh/kodepos/blob/main/app/helpers/kodepos.ts"
    click SH "https://github.com/sooluh/kodepos/blob/main/app/helpers/spec.ts"
    click DS "https://github.com/sooluh/kodepos/blob/main/data/kodepos.json"
    click VER "https://github.com/sooluh/kodepos/blob/main/vercel.json"
```
