# digital-go-jp/abr-geocoder architecture

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

- Interactive diagram: https://gitdiagram.com/digital-go-jp/abr-geocoder
- Repository: https://github.com/digital-go-jp/abr-geocoder

## Overview

Based on our analysis of both the file tree and the README, this project is a specialized geocoding tool for Japanese addresses. It’s designed to be used in multiple ways: as a command-line utility, a Node.js library, and a REST API server. The project also provides additional commands for downloading datasets and checking for updates. In other words, this is a full-stack command/REST/geocoding engine that works with a local SQLite database and leverages multithreading for high-speed processing.

- CLI Interface: Represent the “abrg” commands (download, update-check, geocode, serve start/stop) that enable direct user interaction. Note that the CLI layer is also the integration point for standard I/O and file-based input/output.
- REST API Server: A component launched via “abrg serve start” which exposes endpoints (for instance, /geocode) so that external clients can use the geocoding service.
- Node.js Library: This module encapsulates the geocoding functionality so it can be imported and used programmatically.
- Download and Update Modules: Separate geocoding command use cases that handle dataset downloading from the Digital Agency’s Address Base Registry and checking for updates.
- Domain Layer: Contains business logic including geocoding algorithms, address normalization, various transformations (line-by-line, CSV, JSON, etc.), and error-handling logic.
- Data/Infrastructure Layer: Represents the database using SQLite (with separate drivers for SQLite3 – both general and specialized for different download or geocode functions). Also include file system operations (e.g., making directories, file operations) and the worker thread pool implementations for high-speed multithreaded processing.
- Worker Threads: Indicate components for multithreading (download workers, geocode workers, thread pools, and semaphores) which are predominantly handled in the “src/domain/services/thread” and “src/usecases/geocode/worker” directories.
- External Dependencies: Include external services or references such as the Address Base Registry (data source) and underlying Node.js runtime.

##### Architectural Relationships and Data Flow
- That these use case modules interact with domain services which transform and verify the input addresses.

##### Architectural Patterns and Design Principles
- Separation between different layers (interface, use cases, domain, and infrastructure). This modularity promotes clear boundaries between user interfaces and internal processing.
- Use of multithreading and worker pools which are critical to the system’s high-speed processing.
- Use of “Clean Architecture” or “Hexagonal Architecture” ideas – with the business rules kept isolated from external frameworks (like Node.js or SQLite).

- User Interface Layer: CLI, REST API, possibly linking library usage.
- Application/Use Case Layer: Geocoding, Downloading, Update Check.
- Domain/Business Logic Layer: Address normalization, geocode algorithms, data transformations.
- Infrastructure Layer: Database access layer (SQLite), file system interactions, worker threads, logging.
- Interactions between these layers clearly.
- Optionally, include an “Integration & Test” area reflecting the presence of E2E tests and mocks which help validate each use case.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Interface"]:::interface
        API["REST API Server"]:::interface
        LIB["Node.js Library"]:::interface
    end

    %% Application/Use Case Layer
    subgraph "Application/Use Case Layer"
        DOWNLOAD["Download Module"]:::usecase
        UPDATE["Update Check Module"]:::usecase
        GEOCODE["Geocode Use Case"]:::usecase
    end

    %% Domain/Business Logic Layer
    subgraph "Domain/Business Logic Layer"
        DOMAIN["Domain Services"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DB["SQLite Database"]:::infrastructure
        FILESYS["File System Operations"]:::infrastructure
        WORKER["Worker Threads"]:::infrastructure
        CONFIG["Configuration & Utilities"]:::infrastructure
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        EXTERNAL["Address Base Registry"]:::external
        RUNTIME["Node.js Runtime"]:::external
    end

    %% Connections from UI Layer to Application/Use Case Layer
    CLI -->|"triggers"| DOWNLOAD
    CLI -->|"triggers"| UPDATE
    CLI -->|"triggers"| GEOCODE
    API -->|"calls"| GEOCODE
    LIB -->|"invokes"| GEOCODE

    %% Connections from Application/Use Case Layer to Domain Layer
    DOWNLOAD -->|"processes"| DOMAIN
    UPDATE -->|"processes"| DOMAIN
    GEOCODE -->|"processes"| DOMAIN

    %% Connections from Domain Layer to Infrastructure Layer
    DOMAIN -->|"queries/updates"| DB
    DOMAIN -->|"file ops"| FILESYS
    DOMAIN -->|"multithreading"| WORKER
    DOMAIN -->|"config/log"| CONFIG

    %% External interactions
    EXTERNAL -->|"provides data to"| DOWNLOAD
    RUNTIME -->|"runs"| LIB

    %% Styling Classes
    classDef interface fill:#d4f1c5,stroke:#333,stroke-width:2px,color:#000;
    classDef usecase fill:#c5e1f7,stroke:#333,stroke-width:2px,color:#000;
    classDef domain fill:#f7e1c5,stroke:#333,stroke-width:2px,color:#000;
    classDef infrastructure fill:#f1c5f7,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#e1f7c5,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events
    click CLI "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/interface/cli"
    click CLI "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/interface/cli-server"
    click API "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/interface/abrg-api-server"
    click LIB "https://github.com/digital-go-jp/abr-geocoder/blob/main/src/index.ts"
    click DOWNLOAD "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/usecases/download"
    click DOWNLOAD "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/usecases/download/workers"
    click UPDATE "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/usecases/update-check"
    click DOMAIN "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/domain"
    click DB "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/drivers/database"
    click WORKER "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/domain/services/thread"
    click WORKER "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/usecases/geocode/worker"
    click CONFIG "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/config"
    click CONFIG "https://github.com/digital-go-jp/abr-geocoder/tree/main/src/domain/services/logger"
```
