# tombeom/micro-weather architecture

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

- Interactive diagram: https://gitdiagram.com/tombeom/micro-weather
- Repository: https://github.com/tombeom/micro-weather

## Overview

##### Project type and purpose
- Micro-Weather is a full-stack application consisting of:
a. A Chrome extension (frontend) that provides a popup UI for weather and air-quality data.
b. A lightweight Python API server (backend) that aggregates data from external public APIs, enforces rate limits and blacklists, and returns a unified JSON response.

##### File structure
- Top-level directories:
- extension/ – houses the Chrome extension code (manifest.json, HTML/CSS/JS, assets, Tailwind config).
- server/ – contains the new Python microservice under server/main.py and the microweather package (service, models, database).
- old_server/ – legacy code illustrating earlier server logic and abuse-handling, now superseded by server/.
- Within server/microweather:
- database.py – persistence or caching for station/measurement info
- models.py – data schemas for weather and particulate data
- service.py – business logic orchestrating external API calls
- Configuration files: requirements.txt for Python dependencies, manifest.json for the extension.

##### README for additional insights
- The extension requests geolocation permission and displays data fetched from the backend.
- The backend hides API keys, handles asynchronous external calls, implements CORS headers, rate limiting (429), and blacklist checks (403).
- Future enhancements: aiohttp for non-blocking calls, more robust DDOS protection.

##### Main components
A. Frontend (Chrome Extension)
- Runs in Chrome browser environment
B. Backend (Python Microservice)
- Entry point: server/main.py (WSGI app)
- Business layer: microweather/service.py
- Data layer: microweather/database.py & models.py
- Cross-cutting concerns: CORS handler, rate-limiter, blacklist checker
C. External Services
- Korea Meteorological Administration (KMA) APIs for current & forecast data
- Air-quality measurement station APIs
D. (Optional) Infrastructure / DNS
- Cloud-hosted VM or container running the Python app
- DNS (Cloudflare or custom)

##### Relationships and data flow
2. init.js requests geolocation from browser API.
3. Frontend issues an HTTPS GET to backend endpoint (/weather?lat=…&lon=…).
4. server/main.py receives the request → CORS & abuse checks.
5. service.py calls external KMA and air-quality APIs (possibly asynchronously).
6. database.py may be consulted for station lookup or caching.
7. Aggregated data is packaged into a JSON response by models.py.
8. JSON returns to the extension.

##### Architectural patterns and design principles
- Client-Server separation: clear boundary between UI and data-aggregation service.
- Layered architecture on the backend:
- Presentation (WSGI handler)
- Business logic (service.py)
- Data access/caching (database.py & models.py)
- Adapter pattern: service.py adapts multiple external APIs into a consistent internal model.
- Defensive design: rate limiting, blacklisting, CORS whitelisting.

##### Technologies and frameworks
- Frontend: HTML5, Tailwind CSS, Vanilla JavaScript (manifest v3)
- Backend: Python 3 wsgiref (no heavy framework), asyncio (planned aiohttp), built-in logger
- External: Microsoft Fluent UI Emoji assets

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Extension Zone
    subgraph "Browser Extension" 
        direction TB
        manifest["Manifest (manifest.json)"]:::frontend
        popup["Popup UI (index.html)"]:::frontend
        tailwind["Tailwind Config (tailwind.config.js)"]:::frontend
        inputCSS["CSS Input (input.css)"]:::frontend
        outputCSS["CSS Output (output.css)"]:::frontend
        initJS["Init Script (init.js)"]:::frontend
        drawJS["Render Script (draw.js)"]:::frontend
        images["Image Assets"]:::frontend
    end

    %% Backend Service Zone
    subgraph "Backend Service (Python Microservice)"
        direction TB
        main["WSGI Entry Point (server/main.py)"]:::backend
        cors["CORS Handler"]:::backend
        rate["Rate Limiter"]:::backend
        blacklist["Blacklist Checker"]:::backend
        service["Business Logic (service.py)"]:::backend
        db["Data Access / Caching (database.py)"]:::backend
        models["Data Models (models.py)"]:::backend
    end

    %% External Services
    KMA["KMA APIs"]:::external
    AQ["Air-Quality APIs"]:::external

    %% Data Flow
    manifest --> popup
    popup --> initJS
    initJS -->|"HTTP GET /weather"| main
    main --> cors --> rate --> blacklist --> service
    service --> db
    service --> KMA
    service --> AQ
    service --> models
    models -->|"JSON Response"| drawJS

    %% Click Events
    click manifest "https://github.com/tombeom/micro-weather/blob/main/extension/manifest.json"
    click popup "https://github.com/tombeom/micro-weather/blob/main/extension/src/index.html"
    click tailwind "https://github.com/tombeom/micro-weather/blob/main/extension/tailwind.config.js"
    click inputCSS "https://github.com/tombeom/micro-weather/blob/main/extension/src/input.css"
    click outputCSS "https://github.com/tombeom/micro-weather/blob/main/extension/src/output.css"
    click initJS "https://github.com/tombeom/micro-weather/blob/main/extension/src/scripts/init.js"
    click drawJS "https://github.com/tombeom/micro-weather/blob/main/extension/src/scripts/draw.js"
    click images "https://github.com/tombeom/micro-weather/tree/main/extension/src/images/"
    click main "https://github.com/tombeom/micro-weather/blob/main/server/main.py"
    click service "https://github.com/tombeom/micro-weather/blob/main/server/microweather/service.py"
    click db "https://github.com/tombeom/micro-weather/blob/main/server/microweather/database.py"
    click models "https://github.com/tombeom/micro-weather/blob/main/server/microweather/models.py"
    click rate "https://github.com/tombeom/micro-weather/blob/main/server/requirements.txt"
    click blacklist "https://github.com/tombeom/micro-weather/tree/main/old_server/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
```
