# u22-2025/wip architecture

> Architecture diagram of the GitHub repository u22-2025/wip, 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/u22-2025/wip
- Repository: https://github.com/u22-2025/wip

## Overview

##### Project Type and Purpose
- This is a distributed, protocol‐based networking project implementing the Weather Information Protocol (WIP).
- It provides:
- Client libraries/CLIs (C++, Python, Rust)
- Four UDP-based microservices (Weather/Proxy, Location, Query, Report)
- Data ingestion from external JMA (Japan Meteorological Agency) sources
- Caching layers (Redis), databases (PostgreSQL + PostGIS)

##### File Structure Analysis
- Top-level language folders:
- cpp/  → C++20 client library, tools, CLIs
- python/ → Python server implementations (map, weather_api, tools, mock server)
- Rust/ → Rust client and binary CLIs (deprecated and current)
- src/ → Pure Python packages: WIPClientPy, WIPCommonPy, WIPServerPy
- Config and build:
- CMakeLists.txt, build‐win/, build‐wsl/ (C++ builds)
- pyproject.toml, requirements.txt, yml/env311.yml (Python packaging)
- .env, dotenv for environment variables
- Documentation:
- Lua dissector (Wireshark plugin)
- Cache & memories: internal AI/system caches (.serena, .claude) – not part of runtime

##### README Insights
- Clearly defines 4 server roles (Weather, Location, Query, Report) each listening on different UDP ports.
- Describes protocol stack (Application → UDP → IP → Ethernet).
- Describes external dependencies: PostgreSQL + PostGIS, Redis, external JMA XML/JSON data.
- Illustrates high-level flow: Client ↔ Weather Proxy ↔ Location & Query servers ↔ JMA data source.

a. Main Components
1) Clients:
- C++ CLI (`cpp/build/.../wip_client_cli`)
- Python client library (`src/WIPClientPy`)
- Rust client binaries (`Rust/src/bin/*`)
2) Weather Server (UDP/4110) – Proxy service
3) Location Server (UDP/4109)
4) Query Server (UDP/4111)
5) Report Server (UDP/4112)
6) Data Stores:
- PostgreSQL + PostGIS (for geocoding)
- Redis instances (request cache, log cache)
7) External Data Source:
- 気象庁 (JMA) XML/JSON endpoints
8) Supporting Tools:
- Mock servers, scripts (python/tools/*, cpp/tools/*)
- Wireshark Lua dissector

b. Relationships & Data Flows
1) Client → Weather Server (UDP request on port 4110)
2) Weather Server inspects packet type:
- If coordinate lookup → forward to Location Server → returns area code
- If weather/data request → forward to Query Server → returns weather packet
- If report packet → forward to Report Server
3) Location Server → PostgreSQL/PostGIS (coordinate → area code) + Redis cache
4) Query Server → fetch/process JMA source → Redis cache → packet build → reply
5) Report Server → validate/ingest sensor data → persistent store (DB)
6) All responses travel back via Weather Server → Client

c. Architectural Patterns / Design Principles
- Microservice-style separation per logical function (Proxy vs. Resolution vs. Data Retrieval vs. Reporting)
- UDP request-response, stateless services
- Shared caching (Redis) for performance
- Language-agnostic service endpoints (Rust/Python implementations interchangeable on same ports)
- Extensibility via protocol’s variable extension fields

d. Key Technologies
- Transport: UDP on distinct ports (4110–4112, 4109)
- Protocol: Custom 128-bit header + optional extension fields
- Servers: Python (FastAPI for map UI, custom UDP handlers), Rust (high-performance clients), C++ (packet codec & CLI)
- Databases: PostgreSQL (+PostGIS), Redis (Dragonfly)
- Build: CMake, pip/conda, Cargo

##### Detail Level
- Shared Redis cluster.
- Call out the protocol stack (Application → UDP) in a sidebar or footnote.
- Both runtime flow and data dependencies (caching, persistence).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        CppClient["C++ Client CLI/Library"]:::client
        PyClient["Python Client Library"]:::client
        RustClients["Rust Client Binaries"]:::client
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        WeatherProxy["Weather Proxy Server\n(UDP 4110)"]:::service
        LocationServer["Location Server\n(UDP 4109)"]:::service
        QueryServer["Query Server\n(UDP 4111)"]:::service
        ReportServer["Report Server\n(UDP 4112)"]:::service
    end

    %% Data Processing Tools
    subgraph "Data Processing & Tools"
        direction TB
        DataIngestion["Data Ingestion & Processing"]:::service
        RedisManager["Redis Cache Manager"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["PostgreSQL + PostGIS"]:::datastore
        Redis["Redis (Dragonfly)"]:::datastore
    end

    %% External Source
    JMA["JMA XML/JSON Endpoints"]:::external

    %% Flows
    CppClient -->|UDP Request 4110| WeatherProxy
    PyClient -->|UDP Request 4110| WeatherProxy
    RustClients -->|UDP Request 4110| WeatherProxy

    WeatherProxy -->|coordinate lookup| LocationServer
    WeatherProxy -->|weather/data request| QueryServer
    WeatherProxy -->|report packet| ReportServer

    LocationServer -->|DB lookup| Postgres
    LocationServer -->|cache lookup| Redis

    QueryServer -->|fetch/process| DataIngestion
    DataIngestion -->|cache/store| RedisManager
    QueryServer -->|cache lookup| Redis
    QueryServer -->|reply packet| WeatherProxy

    ReportServer -->|ingest data| Postgres
    ReportServer -->|reply packet| WeatherProxy

    DataIngestion -->|fetch remote| JMA

    %% Responses back to client
    WeatherProxy -->|UDP Response| CppClient
    WeatherProxy -->|UDP Response| PyClient
    WeatherProxy -->|UDP Response| RustClients

    %% Click Events
    click CppClient "https://github.com/u22-2025/wip/tree/main/cpp/"
    click PyClient "https://github.com/u22-2025/wip/tree/main/src/WIPClientPy"
    click RustClients "https://github.com/u22-2025/wip/tree/main/Rust/src/bin"
    click WeatherProxy "https://github.com/u22-2025/wip/tree/main/src/WIPServerPy/servers/weather_server"
    click LocationServer "https://github.com/u22-2025/wip/tree/main/src/WIPServerPy/servers/location_server"
    click QueryServer "https://github.com/u22-2025/wip/tree/main/src/WIPServerPy/servers/query_server"
    click ReportServer "https://github.com/u22-2025/wip/tree/main/src/WIPServerPy/servers/report_server"
    click DataIngestion "https://github.com/u22-2025/wip/tree/main/src/WIPServerPy/data"
    click RedisManager "https://github.com/u22-2025/wip/blob/main/src/WIPServerPy/data/redis_manager.py"
    click LuaDissector "https://github.com/u22-2025/wip/blob/main/lua/wip_dissector.lua"

    %% Styles
    classDef client fill:#daf5ff,stroke:#007acc,stroke-width:2px
    classDef service fill:#e0f7da,stroke:#2e7d32,stroke-width:2px
    classDef datastore fill:#ffe0b2,stroke:#e65100,stroke-width:2px
    classDef external fill:#eeeeee,stroke:#616161,stroke-width:2px
```
