# tkc/go-json-server architecture

> Architecture diagram of the GitHub repository tkc/go-json-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tkc/go-json-server
- Repository: https://github.com/tkc/go-json-server

## Overview

##### Main Components
- Client / Consumer – Represents external users or automated tests interacting with the server (sending HTTP requests).
- API Configuration Loader – A module that reads and parses the JSON configuration file (located in the example directory and used by the server).
- Request Router / Handler – Core component that maps incoming HTTP requests to endpoints based on the configuration (using the src/handler package). This component distinguishes between API endpoints (using json files like health-check.json, users.json, etc.) and static file serving (through the folder attribute in the configuration).
- Middleware Chain – Illustrate the middleware layer (from src/middleware) that includes logging, CORS, panic recovery, request ID assignment, and any additional custom middleware (like authentication in advanced examples).
- Logging Service – The logging component (from src/logger) which provides structured log support (configurable via command-line flags and config settings).
- Configuration Management – Modules in src/config that manage application settings; also includes support for command-line flag overrides.
- File Server – The static file server element designed to serve files from directories (as specified in the configuration, e.g., serving the "static" folder).

##### Relationships and Data Flow
- A client makes an HTTP request toward the go-json-server.
- The request first enters the middleware chain – each middleware function processes the request (e.g., logging, CORS, recovery) before passing it forward.
- The Request Router (or Handler) then inspects the URL and method, compares it with the API configuration from the loaded JSON file, and either:
- Returns a JSON response from one of the configured JSON files (after matching the endpoint and replacing any path parameters).
- Serves static content from a designated folder if the endpoint maps to a file server route.
- The Logger records these interactions, errors, and delivery status.
- The Configuration Loader continuously monitors for changes (hot-reloading) and informs the Router to update endpoints if necessary.

##### Architectural Patterns & Design Principles
- Middleware architecture: A chain of reusable components that process requests.
- Configuration-driven behavior: The endpoints and file serving behaviors are fully dictated by external JSON configuration files.
- Modularity: Different responsibilities are separated in packages (config, handler, middleware, logger).

##### Relevant Technologies and Frameworks
- Go (the primary language) and its native HTTP libraries.
- JSON for configuration and responses.
- GitHub Actions (for CI/CD), as indicated by the workflows.
- Docker (as an optional deployment container technology, per the Dockerfile provided).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client / Consumer"]:::client

    subgraph "Core Server Components"
        F["API Configuration Loader"]:::config
        G["Configuration Management"]:::config
        B["Middleware Chain"]:::processing
        C["Request Router/Handler"]:::processing
        D["JSON API Response"]:::processing
        E["Static File Server"]:::processing
        H["Logging Service"]:::processing
    end

    I["Testing & Build Infrastructure"]:::testing

    A -->|"sendsHTTPRequest"| B
    B -->|"processesRequest"| C
    F -->|"feedsEndpoints"| C
    G -->|"updatesConfig"| C
    C -->|"returnsJSON"| D
    C -->|"servesStatic"| E
    B -->|"logsActivity"| H
    C -->|"logsDelivery"| H
    I -->|"CI_CD_verifies"| B

    click F "https://github.com/tkc/go-json-server/blob/master/example/api.json"
    click F "https://github.com/tkc/go-json-server/blob/master/src/config/config.go"
    click C "https://github.com/tkc/go-json-server/blob/master/src/handler/handler.go"
    click C "https://github.com/tkc/go-json-server/blob/master/example/health-check.json"
    click C "https://github.com/tkc/go-json-server/blob/master/example/users.json"
    click B "https://github.com/tkc/go-json-server/blob/master/src/middleware/middleware.go"
    click H "https://github.com/tkc/go-json-server/blob/master/src/logger/logger.go"
    click G "https://github.com/tkc/go-json-server/blob/master/src/config/config.go"
    click G "https://github.com/tkc/go-json-server/blob/master/src/config/config_test.go"
    click E "https://github.com/tkc/go-json-server/tree/master/example/static"
    click I "https://github.com/tkc/go-json-server/blob/master/.github/workflows/go.yml"
    click I "https://github.com/tkc/go-json-server/blob/master/go-json-server_test.go"
    click I "https://github.com/tkc/go-json-server/blob/master/src/logger/logger_test.go"
    click I "https://github.com/tkc/go-json-server/blob/master/src/middleware/middleware_test.go"
    click I "https://github.com/tkc/go-json-server/blob/master/src/config/config_test.go"

    classDef client fill:#a8d8f0,stroke:#333,stroke-width:2px;
    classDef processing fill:#fceabb,stroke:#333,stroke-width:2px;
    classDef config fill:#ffb347,stroke:#333,stroke-width:2px;
    classDef testing fill:#c1e1c1,stroke:#333,stroke-width:2px;
```
