# jemmia-diamond/fn architecture

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

- Interactive diagram: https://gitdiagram.com/jemmia-diamond/fn
- Repository: https://github.com/jemmia-diamond/fn

## Overview

##### Project type and purpose
- This is a serverless function project built on Cloudflare Workers using the Hono framework.
- It exposes HTTP APIs and Cron-triggered tasks, handling webhooks, RESTful routes, and integrations with multiple external systems (ERPNext, Haravan, Pancake, Larksuite, Inventory-CMS, Zalo, etc.).
- It uses Prisma as an ORM to interact with a relational database for persisting data and migrations.

##### File structure
- Top level:
- wrangler.jsonc – Cloudflare Workers config
- prisma/ – Prisma schemas and migrations
- public/ – Static assets (index.html, robots.txt)
- src/ – Application code
- Under src/:
- index.js – Worker entry point
- routes/ – Hono route definitions (api.js, webhook.js, public-api.js, etc.)
- controllers/ – HTTP request handlers, grouped by namespace/integration
- services/ – Business logic and external-client code (database operations, 3rd-party API clients, utilities)
- auth/, middlewares/ – Authentication and cross-cutting code
- Configuration and tooling:
- ESLint configs, Husky hooks, pnpm, GitHub Actions for linting.

##### Key insights from README
- Main HTTP framework: Hono on Cloudflare Workers (serverless)
- Database migrations via Prisma
- Controllers handle request/response, services hold reusable logic
- Cron triggers supported via Wrangler scheduled endpoints

##### Main components
a. Cloudflare Workers
– The serverless runtime that hosts the Hono application
– Scheduled triggers for Cron jobs
b. Hono App
– Routes layer (src/routes)
– Middleware layer (src/middlewares)
– Controller layer (src/controllers)
c. Services
– Database service (Prisma client connecting to Postgres or MySQL)
– External API clients (ERPNext, Haravan, Pancake, Larksuite, Inventory-CMS, Zalo, Stringee, Nhattin)
– Utility services (logging, CORS, queues, schedulers)
d. Database
– Relational database managed via Prisma migrations
e. Public assets
– Static HTML/robots.txt served on public routes
f. Third-party systems
– ERPNext (via prisma schema & frappe client)
– E-commerce platforms (Haravan, Pancake, etc.)
– Messaging platforms (Zalo, Stringee, Larksuite)

##### Relationships & data flows
- HTTP request → Cloudflare Worker → Hono router → Middleware → Controller
- Controller → Service(s) → Database or External API
- Cron trigger → Worker’s scheduled endpoint → specific Controller(s)/Service(s)
- Services inject clients (Prisma, REST/SDK clients) to call/sync with external systems
- Static assets served directly from public/

##### Architectural patterns & design principles
- Layered architecture: Entry → Routes → Controllers → Services → Data/External
- Separation of concerns: controllers do minimal orchestration, services encapsulate business logic
- Namespacing per integration for modularity
- Serverless event-driven (HTTP & scheduled)
- Infrastructure-as-code via wrangler.jsonc

##### How to represent this
- Route Definitions
- Middleware
- Controllers
- Services
- Database (Prisma ORM → Database)
- External APIs (group each integration: ERPNext, Haravan, Pancake, Larksuite, Inventory-CMS, Zalo, Stringee, Nhattin)
- At the bottom or side, show:
- Public assets bucket (public/)
- Scheduled triggers pointing back into the Hono app
- Blue for internal components (routes/controllers/services)
- Green for external systems
- Orange for infrastructure (Cloudflare Workers, Database)
- HTTP flow: Client → Worker → Routes → Controllers → Services → Database/External
- Cron flow: Scheduler → Worker endpoint → Controller → Service
- Prisma migrations under the Database component to note schema evolution.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime and Config
    subgraph "Cloudflare Workers (Serverless Runtime)" 
        direction TB
        Config["wrangler.jsonc"]:::infra
        Entry["Worker Entry Point<br/>src/index.js"]:::infra
        click Config "https://github.com/jemmia-diamond/fn/blob/main/wrangler.jsonc"
        click Entry "https://github.com/jemmia-diamond/fn/blob/main/src/index.js"

        %% Hono Application Layers
        subgraph "Hono Application"
            direction TB

            %% Routes Layer
            Routes["Route Definitions<br/>src/routes/"]:::internal
            click Routes "https://github.com/jemmia-diamond/fn/tree/main/src/routes/"

            %% Middleware Layer
            subgraph "Middlewares"
                direction TB
                ErrTrack["Error Tracker<br/>error-tracker.js"]:::internal
                ErrHandle["Error Handler<br/>error-handler.js"]:::internal
                click ErrTrack "https://github.com/jemmia-diamond/fn/blob/main/src/middlewares/error-tracker.js"
                click ErrHandle "https://github.com/jemmia-diamond/fn/blob/main/src/middlewares/error-handler.js"
            end

            %% Controllers Layer
            Controllers["Controllers<br/>src/controllers/"]:::internal
            click Controllers "https://github.com/jemmia-diamond/fn/tree/main/src/controllers/"

            %% Services Layer
            Services["Services<br/>src/services/"]:::internal
            click Services "https://github.com/jemmia-diamond/fn/tree/main/src/services/"
        end

        %% Flow: HTTP
        Client -->|HTTP Request| Entry --> Routes --> ErrTrack --> ErrHandle --> Controllers --> Services
        %% Cron Flow
        Scheduler((Cron Scheduler)):::infra
        click Scheduler "https://github.com/jemmia-diamond/fn/blob/main/src/services/schedule-handler.js"
        Scheduler -.->|Cron Trigger| Entry

    end

    %% Database
    Database[(Relational Database<br/>Prisma ORM)]:::database
    PrismaSchema["prisma/schema/schema.prisma"]:::database
    Migrations["prisma/schema/migrations/"]:::database
    click PrismaSchema "https://github.com/jemmia-diamond/fn/blob/main/prisma/schema/schema.prisma"
    click Migrations "https://github.com/jemmia-diamond/fn/tree/main/prisma/schema/migrations/"

    Services -->|Prisma Client| Database
    Database -->|Migrations| PrismaSchema
    Database --> PrismaSchema
    Database --> Migrations

    %% Public Assets
    Public["Public Assets<br/>public/"]:::infra
    click Public "https://github.com/jemmia-diamond/fn/tree/main/public/"

    Entry -->|Static Asset Request| Public

    %% External Integrations
    subgraph "External Systems" 
        direction TB
        ERPNext["ERPNext"]:::external
        click ERPNext "https://github.com/jemmia-diamond/fn/blob/main/src/frappe/frappe-client.js"
        Haravan["Haravan"]:::external
        click Haravan "https://github.com/jemmia-diamond/fn/tree/main/src/services/haravan/api-client/"
        Pancake["Pancake"]:::external
        click Pancake "https://github.com/jemmia-diamond/fn/blob/main/src/pancake/pancake-client.js"
        InventoryCMS["Inventory-CMS"]:::external
        click InventoryCMS "https://github.com/jemmia-diamond/fn/tree/main/src/services/inventory-cms/directus-client/"
        Larksuite["Larksuite"]:::external
        click Larksuite "https://github.com/jemmia-diamond/fn/tree/main/src/services/larksuite/"
        Zalo["Zalo Messaging"]:::external
        click Zalo "https://github.com/jemmia-diamond/fn/tree/main/src/services/zalo-message/"
        Stringee["Stringee Telephony"]:::external
        click Stringee "https://github.com/jemmia-diamond/fn/blob/main/src/stringee/stringee-client.js"
    end

    Services -->|API Calls / SDK| ERPNext
    Services -->|API Calls| Haravan
    Services -->|API Calls| Pancake
    Services -->|API Calls| InventoryCMS
    Services -->|API Calls| Larksuite
    Services -->|API Calls| Zalo
    Services -->|API Calls| Stringee

    %% Queue Handler
    Queue["Queue Handler<br/>src/services/queue-handler.js"]:::internal
    click Queue "https://github.com/jemmia-diamond/fn/blob/main/src/services/queue-handler.js"
    Controllers -->|Enqueue| Queue
    Queue --> Services

    %% Authentication Utilities
    Auth["Auth Utilities<br/>src/auth/"]:::internal
    click Auth "https://github.com/jemmia-diamond/fn/tree/main/src/auth/"
    Controllers --> Auth
    Services --> Auth

    %% Legend
    subgraph "Legend"
        direction TB
        IR["Internal Component"]:::internal
        EX["External System"]:::external
        IF["Infrastructure"]:::infra
        DB["Database"]:::database
    end

    classDef internal fill:#dae8fc,stroke:#6c8ebf,color:#0b1a2f;
    classDef external fill:#d5e8d4,stroke:#82b366,color:#274e13;
    classDef infra fill:#ffe6cc,stroke:#d79b00,color:#663c00;
    classDef database fill:#f8cecc,stroke:#b85450,color:#632424;
```
