# terufujita/bp23 architecture

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

- Interactive diagram: https://gitdiagram.com/terufujita/bp23
- Repository: https://github.com/terufujita/bp23

## Overview

##### Project Type and Purpose
- This is a full-stack “Detour Bot” application that comprises three distinct services:
1. LINE Bot server (Go) for handling Webhook events and replying to users
2. REST API server (Go + Gin) providing data access and business logic for both the bot and a web-based admin UI
3. Web management UI (Next.js) allowing administrators to view and manage routes, spots, and user history
- A shared PostgreSQL database stores users, routes, and spot data, and external route/spot search APIs (OpenRouteService, Gurunavi/HotPepper) supplement suggestions.

##### Directory Structure Insights
- Top-level modules:
- line-bot/
- api-server/
- web-app/
- shared/ (common types/constants)
- docs/ & scripts/ (ancillary)
- Both Go services follow a layered approach (handlers → services → repositories/models, plus pkg for config, DB, utils).
- The web-app uses Next.js 14’s “app” directory with TypeScript, CSS, and framework config files.
- Migrations and environment wrappers (.env.example) live at the root.

##### Key README Takeaways
- Ports:
- LINE Bot → 3001 (with ngrok in dev)
- API Server → 8080
- Web App → 3000
- External dependencies: PostgreSQL, LINE Developers credentials, optional OpenRouteService and spot-search APIs.
- Future plans: full CRUD on the API server, advanced web-UI features, shared library usage.

a. Main Components
- LINE Platform (Messaging API)
- ngrok (dev proxy for exposing Bot on 3001)
- LINE Bot Service
- External Route & Spot Search APIs
- API Server (Gin)
- PostgreSQL Database
- Web Management UI (Next.js)
- (Optionally) Shared library module & future scripts
b. Interactions & Data Flows
1. User → LINE Platform → Webhook → ngrok → LINE Bot
2. LINE Bot ↔ External APIs (route search, spot suggestions)
3. LINE Bot ↔ REST API Server (to persist or query user/route/spot data)
4. API Server ↔ PostgreSQL (CRUD operations via migrations and repository layer)
5. Web UI ↔ API Server (REST calls for display and management)
6. API Server returns responses → Web UI or LINE Bot → end user
c. Architectural Patterns
- Service separation (microservice-style): each service has a single responsibility
- Layered service design in Go modules (handlers, services, repositories, models)
- Shared schema/types in a common module for consistency across services
- Clear API boundary via REST
d. Key Technologies
- Go 1.22+, Gin, pgx/SQL migrations
- Next.js 14, TypeScript, ESLint, PostCSS
- PostgreSQL 14+, ngrok for dev
- External HTTP APIs: OpenRouteService, Gurunavi/HotPepper

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        LINEPlatform["LINE Platform (Messaging API)"]:::external
        RouteAPIs["External Route & Spot Search APIs"]:::external
    end

    %% Development Tools
    subgraph "Development Tools"
        direction TB
        ngrok["ngrok (HTTP Proxy)"]:::dev
    end

    %% Internal Services
    subgraph "Internal Services"
        direction TB
        Bot["LINE Bot Service\n(Go)"]:::internal
        API["API Server (Gin)\n(Go)"]:::internal
        WebUI["Web Management UI\n(Next.js)"]:::internal
        Shared["Shared Types & Config"]:::internal
    end

    %% Database
    DB["PostgreSQL Database"]:::db

    %% Interactions
    LINEPlatform -->|Webhook HTTP| ngrok
    ngrok -->|HTTP 3001| Bot
    Bot -->|Search HTTP| RouteAPIs
    Bot -->|REST API HTTP 8080| API
    API -->|SQL Queries| DB
    WebUI -->|REST API HTTP 8080| API
    Shared -.->|shared schemas| Bot
    Shared -.->|shared schemas| API
    Shared -.->|shared schemas| WebUI

    %% Click Events
    click Bot "https://github.com/terufujita/bp23/tree/develop/line-bot/"
    click API "https://github.com/terufujita/bp23/tree/develop/api-server/"
    click WebUI "https://github.com/terufujita/bp23/tree/develop/web-app/"
    click Shared "https://github.com/terufujita/bp23/blob/develop/.env.example"

    %% Styles
    classDef internal fill:#b0f2b6,stroke:#4CAF50,stroke-width:2px;
    classDef external fill:#b3e5fc,stroke:#2196F3,stroke-width:2px;
    classDef db fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef dev fill:#e1bee7,stroke:#9c27b0,stroke-width:2px;
```
