# nawashiro/nos-hagaki architecture

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

- Interactive diagram: https://gitdiagram.com/nawashiro/nos-hagaki
- Repository: https://github.com/nawashiro/nos-hagaki

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (App Router) that serves as a Nostr client in which users are mapped to random points on Earth and message delivery is delayed based on geographic distance.
- It uses React server and client components, Prisma for database modeling and migrations, Redis utilities for caching or coordination, and serverless API routes plus a cron job for batch dispatch.

##### File structure
- Top-level “app” directory: Next.js page and layout routes, split into pre-login and post-login flows, with subfolders for simple and timeline layouts, mailbox (“postoffice”), profile editing, search, settings, etc.
- “app/api”: serverless routes: a cron entrypoint + a post-insert endpoint.
- “components”: reusable UI components for cards, dialogs, maps, buttons.
- “prisma”: schema.prisma & migrations → relational DB (likely PostgreSQL).
- “src”: domain utilities: NDK singleton wrappers, data-fetching, geo lookups, Redis helpers.
- Config files: next.config.js, tsconfig.json, tailwind.config.ts, postcss.config.js.
- Static assets: public/geojson map data, public/img.
- Middleware (middleware.ts) for auth/redirects.

##### README for additional insights
- Confirms use of NIP-07 browser extension for authentication.
- Mentions batch send logic (“一日に一度バッチ処理する”).
- Roadmap indicates core features completed: timelines, post drafting, send confirmation, profile, search, follow lists, distance/time calculation.

##### Main components & their interactions
a. Frontend (Next.js)
- App router pages: login, timelines, post-draft editor, confirmation, complete screens, profile, search, settings.
- UI components render posts, profiles, interactive maps, dialogs.
- Client components call serverless API endpoints or directly import shared “src” utilities for real-time fetch via NDK.
b. API layer (serverless functions)
- /api/post-insert: inserts outgoing messages into a “send queue” in the database.
- /api/cron: invoked via Vercel cron to process the queue and forward messages through NDK.
c. Database (Prisma)
- Stores user mappings, draft posts, send-queue records, follow relationships, settings.
d. Redis
- Caching of geo lookups, rate-limiting, possibly coordination locks for cron jobs.
e. External services
- Nostr network via NDK (NDKSingleton, ServerNDKSingleton).
- GeoJSON data for world map.

##### Architectural patterns & design principles
- Separation of concerns: UI in “components”, routing in “app”, domain logic in “src”, persistence in Prisma/Redis.
- Serverless micro-endpoints for side effects.
- Batch processing via scheduled cron function.
- React Server Components for server-side rendered content.
- Client Components for interactivity (map, dialogs).
- Singletons for Nostr event streams.

##### Detail
- Layout (simple, timeline), each API route, and both data-insertion and data-dispatch paths.
- Middleware at the edge for auth/redirect.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js)"
        direction TB
        Browser["Browser (NIP-07)"]:::frontend
        Middleware["middleware.ts"]:::backend
        subgraph "Pre-Login Flow"
            PreLogin["app/(before-login)"]:::frontend
        end
        subgraph "Post-Login Flow"
            direction TB
            subgraph "Simple Layout"
                SimpleLayout["app/(after-login)/(simple)"]:::frontend
            end
            subgraph "Timeline Layout"
                TimelineLayout["app/(after-login)/(timeline)"]:::frontend
            end
        end
        Components["components/"]:::frontend

        Browser -->|uses| PreLogin
        PreLogin -->|auth check| Middleware
        Middleware -->|routes to| SimpleLayout
        Middleware -->|routes to| TimelineLayout
        SimpleLayout -->|uses| Components
        TimelineLayout -->|uses| Components
    end

    %% API Layer
    subgraph "API (Serverless Functions)"
        direction TB
        PostInsert["/api/post-insert"]:::api
        CronJob["/api/cron"]:::api

        SimpleLayout -->|POST message| PostInsert
        TimelineLayout -->|trigger batch| CronJob
    end

    %% Domain Utilities
    subgraph "Domain Utilities (src)"
        direction TB
        RedisUtil["src/redisUtil.ts"]:::utils
        NDKClient["src/NDKSingleton.ts"]:::utils
        NDKServer["src/ServerNDKSingleton.ts"]:::utils
        NDKEventList["src/NDKEventList.ts"]:::utils
        FetchData["src/fetchData.ts"]:::utils
        GeoLookup1["src/getCountryName.ts"]:::utils
        GeoLookup2["src/getRegions.ts"]:::utils
        IPUtil["src/getIp.ts"]:::utils
        Context["src/context.ts"]:::utils
        AgreeCheck["src/agreeCheck.ts"]:::utils

        PostInsert -->|uses| RedisUtil
        PostInsert -->|inserts to| Postgres
        PostInsert -->|invokes| NDKServer

        CronJob -->|locks via| RedisUtil
        CronJob -->|reads from| Postgres
        CronJob -->|sends via| NDKServer

        SimpleLayout -->|fetch data via| FetchData
        TimelineLayout -->|fetch data via| FetchData
        FetchData -->|streams via| NDKClient
        NDKClient -->|subscribes to| Nostr
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        Postgres["PostgreSQL\n(schema.prisma)"]:::db
        Migrations["prisma/migrations/"]:::db
        RedisCache["Redis"]:::db

        RedisUtil --> RedisCache
        Postgres --> Migrations
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Nostr["Nostr Relays"]:::external
        GeoJSON["GeoJSON\n(public/geojson/mundo.geojson)"]:::external
        Images["Images\n(public/img/)"]:::external

        SimpleLayout -->|loads| GeoJSON
        TimelineLayout -->|loads| GeoJSON
        Components -->|renders| Images
        NDKServer -->|publishes to| Nostr
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        Styles["app/globals.css\ntailwind.config.ts"]:::config
        Config["next.config.js\ntsconfig.json"]:::config
    end

    %% Click Events
    click PreLogin "https://github.com/nawashiro/nos-hagaki/tree/main/app/(befor-login)"
    click SimpleLayout "https://github.com/nawashiro/nos-hagaki/tree/main/app/(after-login)/(simple)"
    click TimelineLayout "https://github.com/nawashiro/nos-hagaki/tree/main/app/(after-login)/(timeline)"
    click PostInsert "https://github.com/nawashiro/nos-hagaki/blob/main/app/api/post-insert/route.ts"
    click CronJob "https://github.com/nawashiro/nos-hagaki/blob/main/app/api/cron/route.ts"
    click Components "https://github.com/nawashiro/nos-hagaki/tree/main/components/"
    click Postgres "https://github.com/nawashiro/nos-hagaki/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/nawashiro/nos-hagaki/tree/main/prisma/migrations/"
    click RedisUtil "https://github.com/nawashiro/nos-hagaki/blob/main/src/redisUtil.ts"
    click NDKClient "https://github.com/nawashiro/nos-hagaki/blob/main/src/NDKSingleton.ts"
    click NDKServer "https://github.com/nawashiro/nos-hagaki/blob/main/src/ServerNDKSingleton.ts"
    click NDKEventList "https://github.com/nawashiro/nos-hagaki/blob/main/src/NDKEventList.ts"
    click FetchData "https://github.com/nawashiro/nos-hagaki/blob/main/src/fetchData.ts"
    click GeoLookup1 "https://github.com/nawashiro/nos-hagaki/blob/main/src/getCountryName.ts"
    click GeoLookup2 "https://github.com/nawashiro/nos-hagaki/blob/main/src/getRegions.ts"
    click IPUtil "https://github.com/nawashiro/nos-hagaki/blob/main/src/getIp.ts"
    click Context "https://github.com/nawashiro/nos-hagaki/blob/main/src/context.ts"
    click AgreeCheck "https://github.com/nawashiro/nos-hagaki/blob/main/src/agreeCheck.ts"
    click Middleware "https://github.com/nawashiro/nos-hagaki/blob/main/middleware.ts"
    click Styles "https://github.com/nawashiro/nos-hagaki/blob/main/app/globals.css"
    click Styles "https://github.com/nawashiro/nos-hagaki/blob/main/tailwind.config.ts"
    click Config "https://github.com/nawashiro/nos-hagaki/blob/main/next.config.js"
    click Config "https://github.com/nawashiro/nos-hagaki/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#B3CDE3,stroke:#036;fill-opacity:0.3
    classDef backend fill:#C7E9C0,stroke:#070;fill-opacity:0.3
    classDef api fill:#A6CEE3,stroke:#028;fill-opacity:0.3
    classDef utils fill:#F0E68C,stroke:#AA0;fill-opacity:0.3
    classDef db fill:#FDBF6F,stroke:#D85;fill-opacity:0.3
    classDef external fill:#CAB2D6,stroke:#720;fill-opacity:0.3
    classDef config fill:#DDCCFF,stroke:#55;fill-opacity:0.3
```
