# mshumayl/cidr-checkr architecture

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

- Interactive diagram: https://gitdiagram.com/mshumayl/cidr-checkr
- Repository: https://github.com/mshumayl/cidr-checkr

## Overview

##### Project type and purpose
- This is a Go‑based, headless HTTP API server (“cidr‑checkr”) that exposes CIDR analysis and overlap‑detection functionality.
- Its primary audience is network engineers, security teams, and DevOps pipelines that need to validate or audit IP ranges.

##### File structure
- Top‑level “cmd/api” holds the entry point (main.go) which spins up an HTTP server.
- “internal/handlers” implements HTTP handlers (routing, request parsing, response formatting).
- “internal/service” contains the core CIDR analysis logic (overlap detection, first/last IP calculations).
- “internal/models” defines the request/response data structures.
- No database/persistence layer—this is an in-memory, compute‑only service.

##### Key insights from the README
- REST API with a single POST endpoint `/api/analyze-cidrs`.
- JSON request → list of CIDRs; JSON response → per‑CIDR details + overlap info.
- Intended for integration into automation or CI/CD pipelines.

- External client (e.g., curl, CLI, dashboard, CI job)
- HTTP API server (cmd/api)
- Router/handler layer (internal/handlers)
- Service layer (internal/service/analyzer)
- Data models (internal/models)
b. Relationships & interactions:
1. Client issues HTTP POST → API server listens on :8080
2. Router dispatches request to the appropriate handler
3. Handler unmarshals JSON into model structs
4. Handler calls the analyzer service with the list of CIDRs
5. Service executes analysis: for each CIDR compute first/last IP & hosts, detect overlaps
6. Service returns a result struct back to handler
7. Handler marshals the model to JSON and writes HTTP response
c. Architectural patterns/design principles:
- Layered (API → Handler → Service → Model)
- Single‑responsibility modules: each package has a clear role
- In‑process, stateless microservice (no DB, no persistent state)
- Test coverage at handler and service levels (as shown by `*_test.go`)
d. Relevant technologies/frameworks:
- Go “net/http” standard library (or a lightweight router)
- JSON marshalling/unmarshalling (encoding/json)
- Native Go testing (go test)
- Go modules (go.mod)

##### Detailed elements
- Endpoint URL and HTTP method
- Input/Output JSON schemas (request/response model fields)
- Test hooks or mention of unit test packages
- Optionally, note “no external database” to emphasize statelessness

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client<br/>(curl, CI/CD)"]:::external
    API["HTTP API Server<br/>cmd/api/main.go"]:::module
    Handler["Router/Handlers Layer<br/>internal/handlers/handlers.go"]:::module
    Models["Data Models<br/>internal/models/models.go"]:::module
    Service["Service Layer<br/>internal/service/analyzer.go"]:::module
    NoDB["No External Database<br/>(Stateless)"]:::annotation
    HandlerTest["Handlers Tests<br/>internal/handlers/handlers_test.go"]:::test
    ServiceTest["Service Tests<br/>internal/service/analyzer_test.go"]:::test

    Client -->|"POST /api/analyze-cidrs"| API
    API -->|"delegate request"| Handler
    Handler -->|"Unmarshal JSON"| Models
    Handler -->|"calls Analyze()"| Service
    Service -->|"use models for structs"| Models
    Service -->|"returns result structs"| Handler
    Handler -->|"Marshal JSON"| API
    API -->|"HTTP Response"| Client

    HandlerTest -.->|tests| Handler
    ServiceTest -.->|tests| Service

    %% Click Events
    click API "https://github.com/mshumayl/cidr-checkr/blob/master/cmd/api/main.go"
    click Handler "https://github.com/mshumayl/cidr-checkr/blob/master/internal/handlers/handlers.go"
    click Service "https://github.com/mshumayl/cidr-checkr/blob/master/internal/service/analyzer.go"
    click Models "https://github.com/mshumayl/cidr-checkr/blob/master/internal/models/models.go"
    click HandlerTest "https://github.com/mshumayl/cidr-checkr/blob/master/internal/handlers/handlers_test.go"
    click ServiceTest "https://github.com/mshumayl/cidr-checkr/blob/master/internal/service/analyzer_test.go"

    %% Styles
    classDef external fill:#9f6,stroke:#333,stroke-width:1px
    classDef module fill:#6af,stroke:#333,stroke-width:1px
    classDef test fill:#fc6,stroke:#333,stroke-width:1px
    classDef annotation fill:#eee,stroke-dasharray: 3 3,stroke:#666,stroke-width:1px
```
