# jolav/codetabs architecture

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

- Interactive diagram: https://gitdiagram.com/jolav/codetabs
- Repository: https://github.com/jolav/codetabs

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Go web application (“codetabs.com”) that exposes multiple small REST-style API services (count-loc, CORS proxy, GitHub/GitLab stars, IP geolocation, Alexa ranking, HTTP headers, weather, random data) and serves a static single-page UI for each service from the “www” directory.

a. Client (Browser)
- Static UI pages (HTML/CSS/JS) under www/…
- One SPA per tool that issues AJAX/JSON or JSONP calls
b. API Server (Go Application)
- main.go: HTTP router, handler registration, static fileserver
- Service modules (each in its own directory: loc, proxy, stars, geolocation, alexa, headers, weather, random)
- Shared utils in _utils/ (JSON marshaling, HTTP clients, stats, random, networking helpers)
- Data layer:
– _data/… CSV and text files (Alexa top-1m, IP geolocation data, random surnames)
– store/… in-memory cache or persistence for rate-limiting or reuse (store/store.go, store/loc.go, store/stars.go)
c. External Dependencies
- GitHub and GitLab REST APIs
- Alexa CSV download
- IP2Location geolocation data
- Public weather API (via IP geolocation)
- Boyter/scc CLI invoked for LOC counting
d. Development tooling
- Air (live reloading via .air.toml)
- go.mod/go.sum for dependency management

##### Interactions and data flow
- Browser → HTTP GET “/count-loc” or “/api/count-loc?…”
- Router dispatches to the LocService handler
- LocService calls:
- store/loc.go (cache lookup)
- if miss, launches scc, processes its JSON output
- Response marshaled via utils.responses → JSON sent back
- Similar flows for stars, geolocation, Alexa (reads CSV), headers (follows redirects via utils.network), weather (combines geolocation + weather API), random (reads surnames.txt or generates ints)
- CORS proxy simply streams external URLs back to client

##### Architectural patterns and design principles
- Layered approach:
- HTTP layer (router + handlers)
- Service/business logic layer (one module per endpoint)
- Data access / caching layer
- Shared cross-cutting utilities (logging/stats/utils)
- Modularization by feature (each service in its own package)
- Single monolith process—no microservices or separate deployments
- Static assets served from embedded file server

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client (Browser/UI)"
        UI["Static UI (HTML/JS/CSS)"]:::ui
    end

    subgraph "API Server (Go)"
        Router["HTTP Router & Static File Server"]:::server

        subgraph "Service Modules"
            LOC["Loc Service"]:::service
            PROXY["CORS Proxy Service"]:::service
            STARS["Stars Service"]:::service
            GEO["Geolocation Service"]:::service
            ALEXA["Alexa Ranking Service"]:::service
            HEADERS["HTTP Headers Service"]:::service
            WEATHER["Weather Service"]:::service
            RANDOM["Random Data Service"]:::service
        end

        subgraph "Shared Utilities"
            JSONU["JSON Utils"]:::utils
            NETWORK["Network Utils"]:::utils
            NUMBERS["Numbers Utils"]:::utils
            RESP["Response Utils"]:::utils
            STATS["Stats Utils"]:::utils
            UTILS["General Utils"]:::utils
        end

        subgraph "Data Store & Cache"
            ALDATA["Alexa CSV (top-1m)"]:::data
            GEODATA["Geo Data File"]:::data
            SCCD["LOC SCC Data"]:::data
            SURNAMES["Random Surnames"]:::data
            CACHESTORE["In-memory Cache"]:::cache
        end
    end

    subgraph "External Systems"
        GHAPI["GitHub/GitLab APIs"]:::external
        ALEXAEXT["Alexa CSV Source"]:::external
        IP2LOC["IP2Location Data"]:::external
        WEATHERAPI["Public Weather API"]:::external
        SCCCLI["Boyter/scc CLI"]:::external
    end

    UI -->|"HTTP/HTTPS"| Router
    Router --> LOC
    Router --> PROXY
    Router --> STARS
    Router --> GEO
    Router --> ALEXA
    Router --> HEADERS
    Router --> WEATHER
    Router --> RANDOM

    LOC -->|cache lookup| CACHESTORE
    LOC -->|exec scc| SCCCLI
    LOC -->|uses data| SCCD
    LOC -->|respond| RESP

    PROXY -->|streams external URLs| GHAPI
    PROXY -->|streams external URLs| ALEXAEXT

    STARS -->|cache lookup| CACHESTORE
    STARS -->|calls GitHub/GitLab| GHAPI
    STARS -->|respond| RESP

    GEO -->|reads file| GEODATA
    GEO -->|calls IP2Location| IP2LOC
    GEO -->|respond| RESP

    ALEXA -->|reads file| ALDATA
    ALEXA -->|respond| RESP

    HEADERS -->|follow redirects| NETWORK
    HEADERS -->|respond| RESP

    WEATHER -->|uses GEO module| GEO
    WEATHER -->|calls weather API| WEATHERAPI
    WEATHER -->|respond| RESP

    RANDOM -->|reads file| SURNAMES
    RANDOM -->|generate ints| NUMBERS
    RANDOM -->|respond| RESP

    LOC -->|marshal| JSONU
    PROXY -->|marshal| JSONU
    STARS -->|marshal| JSONU
    GEO -->|marshal| JSONU
    ALEXA -->|marshal| JSONU
    HEADERS -->|marshal| JSONU
    WEATHER -->|marshal| JSONU
    RANDOM -->|marshal| JSONU

    click UI "https://github.com/jolav/codetabs/tree/master/www/"
    click Router "https://github.com/jolav/codetabs/blob/master/main.go"
    click LOC "https://github.com/jolav/codetabs/blob/master/loc/loc.go"
    click PROXY "https://github.com/jolav/codetabs/blob/master/proxy/proxy.go"
    click STARS "https://github.com/jolav/codetabs/blob/master/stars/stars.go"
    click GEO "https://github.com/jolav/codetabs/blob/master/geolocation/geolocation.go"
    click ALEXA "https://github.com/jolav/codetabs/blob/master/alexa/alexa.go"
    click HEADERS "https://github.com/jolav/codetabs/blob/master/headers/headers.go"
    click WEATHER "https://github.com/jolav/codetabs/blob/master/weather/weather.go"
    click RANDOM "https://github.com/jolav/codetabs/blob/master/random/random.go"

    click JSONU "https://github.com/jolav/codetabs/blob/master/_utils/json.go"
    click NETWORK "https://github.com/jolav/codetabs/blob/master/_utils/network.go"
    click NUMBERS "https://github.com/jolav/codetabs/blob/master/_utils/numbers.go"
    click RESP "https://github.com/jolav/codetabs/blob/master/_utils/responses.go"
    click STATS "https://github.com/jolav/codetabs/blob/master/_utils/stats.go"
    click UTILS "https://github.com/jolav/codetabs/blob/master/_utils/utils.go"

    click ALDATA "https://github.com/jolav/codetabs/blob/master/_data/alexa/top-1m.csv"
    click GEODATA "https://github.com/jolav/codetabs/blob/master/_data/geolocation/downloadLink.txt"
    click SCCD "https://github.com/jolav/codetabs/tree/master/_data/loc/scc/"
    click SURNAMES "https://github.com/jolav/codetabs/blob/master/_data/random/surnames.txt"

    click CACHESTORE "https://github.com/jolav/codetabs/blob/master/store/store.go"
    click CACHESTORE "https://github.com/jolav/codetabs/blob/master/store/loc.go"
    click CACHESTORE "https://github.com/jolav/codetabs/blob/master/store/stars.go"

    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef server fill:#cff,stroke:#333,stroke-width:1px
    classDef service fill:#fcf,stroke:#333,stroke-width:1px
    classDef utils fill:#cfc,stroke:#333,stroke-width:1px
    classDef data fill:#ccf,stroke:#333,stroke-width:1px
    classDef cache fill:#ffc,stroke:#333,stroke-width:1px
    classDef external fill:#eef,stroke:#333,stroke-width:1px
```
