# remy/mit-license architecture

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

- Interactive diagram: https://gitdiagram.com/remy/mit-license
- Repository: https://github.com/remy/mit-license

## Overview

##### Project Type and Purpose
- This is a Node.js/Express “full-stack” web service (mostly backend) that dynamically generates MIT (or ISC) license pages per user.
- It exposes HTTP endpoints (GET/POST) to serve HTML or text license views, with customizable themes and options.
- Data is stored as JSON files under `/users` (no external database). Templates are in `/licenses`, static assets (CSS themes) under `/themes`, and utility code in `/lib` and `/utils`.

##### File Structure
- Top‐level entry: `server.js` – bootstraps the Express app, mounts routes, static middleware, template engine (EJS).
- `routes/` – `get.js` and `post.js` define HTTP endpoints for fetching or creating/updating user JSON data.
- `lib/` – business logic modules `load-user.js` (reads/parses `users/<id>.json`), `load-options.js` (applies URL parameters & defaults).
- `utils/` – helper `is-domain-id.js` validates domain‐style user IDs.
- `licenses/` – EJS templates (`ISC.ejs`, `MIT.ejs`) plus header/footer components.
- `themes/` – ~200 CSS theme files, served statically; chosen per user via JSON `theme` property.
- `users/` – file‐based data store: each JSON file is a user record specifying copyright, URL, email, format, gravatar, theme, etc.
- `Procfile` – declares the Heroku web process.
- Config: `package.json`, `.gitignore`, `.editorconfig`, GitHub CI workflows.

##### Key README Insights
- API supports GET (render HTML/text) and POST (create user JSON on the fly).
- Uses EJS for templating; static CSS for theme variants.
- Deployment on Heroku behind CloudFlare (DNS, SSL).
- No external DB – JSON files in repo or created via API.

##### Main Components & Interactions
a. External Clients & DNS Layer
– Users’ browsers or curl requests → DNS / CloudFlare → Heroku routing/load balancer
b. Web Tier (Express App)
- `server.js`: initializes Express, mounts:
– Static middleware serving `/themes`, `/assets`, license template CSS/Sketch assets
– Route handlers:
– GET `/[:user]/[year-range]/[license.(html|txt)]` → `routes/get.js`
– POST `/?…` → `routes/post.js`
- Business logic:
– `load-options.js`: parse URL or POST body into options (year, format, license type)
– `is-domain-id.js`: validate incoming user identifier
– `load-user.js`: read/validate `users/<user>.json` or create new JSON if POST
- Template Engine & Views:
– EJS picks `licenses/MIT.ejs` or `licenses/ISC.ejs`, injects data + theme CSS link, gravatar, etc.
c. Data Layer (File System)
– Read/write JSON under `/users` on disk/repo
– License templates under `/licenses`
– Static CSS under `/themes`
d. External Services
– CloudFlare (DNS, SSL, CDN)
– Heroku (hosting, dyno management)
– Gravatar (if enabled: external avatar fetch)
– GitHub (CI, source repo, user‐data updates via PRs)

##### Architectural Patterns & Principles
- Layered MVC‐like separation:
– Model: JSON “users” file store
– Controller: route handlers (`routes/*.js`) + business logic (`lib/*`)
– View: EJS templates + static CSS (themes)
- File‐based data store in lieu of traditional database; caching could be added.
- 12‐factor friendly: environment on Heroku, Procfile, no sticky state aside from JSON in ephemeral dyno (persist via git PR or external storage).
- Extensibility: new themes by dropping CSS in `/themes`; new users by POST or PR.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients & DNS Layer
    subgraph "Users & DNS Layer"
        direction TB
        Client["Client (Browser/curl)"]:::external
        CloudFlare["CloudFlare DNS/CDN"]:::external
        HerokuRouter["Heroku Router/Load Balancer"]:::external
    end

    Client -->|HTTP/HTTPS| CloudFlare
    CloudFlare -->|HTTP/HTTPS| HerokuRouter

    %% Hosting Tier
    subgraph "Hosting & Runtime"
        direction TB
        Dyno["Dyno Process\n(Procfile)"]:::compute
    end

    HerokuRouter --> Dyno

    %% Web Tier: Express App
    subgraph "Web Tier (Express App)" 
        direction TB
        Express["Express App\n(server.js)"]:::compute
        StaticMiddleware["Static Middleware\n(themes/, assets/)"]:::static
        subgraph "Route Controllers"
            direction TB
            GETRoute["GET Route Controller\n(routes/get.js)"]:::compute
            POSTRoute["POST Route Controller\n(routes/post.js)"]:::compute
        end
        subgraph "Business Logic Modules"
            direction TB
            LoadOptions["Load Options\n(lib/load-options.js)"]:::compute
            ValidateID["Validate User-ID\n(utils/is-domain-id.js)"]:::compute
            LoadUser["Load User Data\n(lib/load-user.js)"]:::compute
        end
        subgraph "Template Engine & Views"
            direction TB
            EJS["EJS Engine"]:::compute
            MITTemplate["MIT Template\n(licenses/MIT.ejs)"]:::compute
            ISCTemplate["ISC Template\n(licenses/ISC.ejs)"]:::compute
            HeaderComp["Header Partial\n(licenses/components/header.ejs)"]:::compute
            FooterComp["Footer Partial\n(licenses/components/footer.ejs)"]:::compute
        end
    end

    Dyno --> Express
    Express --> StaticMiddleware
    StaticMiddleware -->|serves CSS| themesDir
    StaticMiddleware -->|serves assets| AssetsDir

    Express --> GETRoute
    Express --> POSTRoute

    GETRoute -->|parse URL/Body| LoadOptions
    POSTRoute -->|parse URL/Body| LoadOptions

    LoadOptions --> ValidateID
    ValidateID --> LoadUser
    LoadUser -->|read/write JSON| UsersDir

    LoadUser --> EJS
    EJS --> MITTemplate
    EJS --> ISCTemplate
    MITTemplate --> HeaderComp
    MITTemplate --> FooterComp
    ISCTemplate --> HeaderComp
    ISCTemplate --> FooterComp

    EJS --> Express
    Express -->|render HTML/text| Client

    %% External Services
    subgraph "External Services"
        direction TB
        Gravatar["Gravatar API"]:::external
        GitHub["GitHub (CI & PRs)"]:::external
    end

    Express -->|fetch avatar if enabled| Gravatar
    Developer["Developer"]:::external
    Developer -->|PR updates| GitHub
    GitHub -->|update files| UsersDir

    %% File System Data Stores
    subgraph "File System Storage"
        direction TB
        UsersDir["User JSON Store\n(users/)"]:::storage
        themesDir["CSS Themes Directory\n(themes/)"]:::static
        AssetsDir["Static Assets\n(assets/Logo.sketch)"]:::static
    end

    %% Config & CI
    subgraph "Config & CI"
        direction TB
        PackageJSON["package.json"]:::storage
        ProcfileNode["Procfile"]:::storage
        CIWorkflow[".github/workflows/main.yml"]:::storage
    end

    %% Click Events
    click Express "https://github.com/remy/mit-license/blob/master/server.js"
    click GETRoute "https://github.com/remy/mit-license/blob/master/routes/get.js"
    click POSTRoute "https://github.com/remy/mit-license/blob/master/routes/post.js"
    click LoadUser "https://github.com/remy/mit-license/blob/master/lib/load-user.js"
    click LoadOptions "https://github.com/remy/mit-license/blob/master/lib/load-options.js"
    click ValidateID "https://github.com/remy/mit-license/blob/master/utils/is-domain-id.js"
    click MITTemplate "https://github.com/remy/mit-license/blob/master/licenses/MIT.ejs"
    click ISCTemplate "https://github.com/remy/mit-license/blob/master/licenses/ISC.ejs"
    click HeaderComp "https://github.com/remy/mit-license/blob/master/licenses/components/header.ejs"
    click FooterComp "https://github.com/remy/mit-license/blob/master/licenses/components/footer.ejs"
    click themesDir "https://github.com/remy/mit-license/tree/master/themes/"
    click AssetsDir "https://github.com/remy/mit-license/blob/master/assets/Logo.sketch"
    click UsersDir "https://github.com/remy/mit-license/tree/master/users/"
    click ProcfileNode "https://github.com/remy/mit-license/tree/master/Procfile"
    click PackageJSON "https://github.com/remy/mit-license/blob/master/package.json"
    click CIWorkflow "https://github.com/remy/mit-license/blob/master/.github/workflows/main.yml"

    %%Styles
    classDef compute fill:#D0E8FF,stroke:#005B96
    classDef storage fill:#DFF0D8,stroke:#3C763D
    classDef external fill:#FEE5D9,stroke:#E06666
    classDef static fill:#EEEEEE,stroke:#777777
```
