# ccap-project/configmanager architecture

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

- Interactive diagram: https://gitdiagram.com/ccap-project/configmanager
- Repository: https://github.com/ccap-project/configmanager

## Overview

##### Project type and purpose
- This is a monolithic, backend-focused RESTful service in Go, generated via go-swagger, plus a minimal static HTML/JS UI.
- Its purpose is to manage “cells,” “components,” “customers,” “networks,” etc., storing relationships in a Neo4j graph database.

##### File structure
- cmd/config-manager-server/main.go – application entry point (initializes config, HTTP server).
- etc/config.yaml – runtime configuration (DB URL, ports, credentials).
- restapi/… – go-swagger generated server stub, routers, operations for every resource (cell, component, customer, host, etc.).
- handlers/… – your HTTP handlers (“controllers”), wiring swagger operations to business logic.
- models/… – domain structs (Customer, Cell, Network, etc.) auto-generated to match Swagger spec plus ULID helpers.
- neo4j/main.go – Neo4j driver initialization and DB session management.
- html/index.html & html/root.js – static single-page UI served by the same binary.
- util/util.go – shared helper functions (error formatting, common utilities).
- swagger/swagger.yml – API specification (source of truth).
- Makefile, govendor, swagger scripts – build and codegen tooling.

##### README
- Instructs on syncing dependencies via govendor.
- Instructs on regenerating server stubs/models with go-swagger.

A. HTTP/API Layer
– go-swagger router (restapi/server.go)
– Supports Swagger UI under /swagger/ui and JSON spec at /swagger.yaml
B. Controller/Handler Layer
– handlers/*.go implement business operations per resource
C. Domain Model Layer
D. Persistence Layer
– neo4j/*: Neo4j driver, session management, Cypher query wrappers
E. Configuration
– etc/config.yaml loaded at startup (DB credentials, server port)
F. Static UI
– html/index.html & root.js served via an embedded file server
– govendor for vendoring
– go-swagger codegen (swagger generate server …)

1. Client (browser or API client) → HTTP Server
2. HTTP Server → Swagger router → specific Operation handler
3. Handler → Domain model validation → Calls Persistence layer
4. Persistence layer → Neo4j DB → returns records
5. Handler → transforms DB records into models → writes HTTP response
6. Static UI requests index.html → served from binary → JS calls API endpoints

##### Architectural patterns & principles
- “MVC-light”:
– C: swagger router + handlers
– M: models/*.go
– V: JSON over HTTP, plus static HTML/JS
- Hexagonal/Ports & Adapters:
– Adapters: HTTP transport (swagger), Neo4j driver
– Core: business logic in handlers + util
- Single-process monolith (no separate microservices)

##### Technologies & frameworks
- Go language
- go-swagger (0.13.0) – API spec, server stub generation
- Neo4j (graph database) via official Go driver
- govendor – dependency management
- Embedded static assets (html, JS) in Go binary

##### Final checklist
- All main runtime components shown (HTTP, Handlers, Models, DB, UI, Config).
- Optional: note the codegen step off to the side, showing swagger.yml → Go code.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client and UI
    Client["Client (Browser/API)"]:::external
    StaticUI["Static UI\n(html/index.html, html/root.js)"]:::code
    Client -->|"Requests UI"| StaticUI
    Client -->|"JSON API Calls"| SwaggerRouter

    %% Configuration
    Config[(etc/config.yaml)]:::database
    Config --> Main

    %% Entry Point
    Main["Application Entry Point\n(cmd/config-manager-server/main.go)"]:::code

    Main --> SwaggerRouter
    Main --> Handler
    Main --> Persistence

    %% HTTP/API Layer
    subgraph "HTTP/API Layer"
        SwaggerRouter["Swagger Router\n(restapi/server.go, configure_config_manager.go)"]:::code
        EmbeddedSpec["Embedded Spec\n(restapi/embedded_spec.go)"]:::code
        Operations["Operations\n(restapi/operations/)"]:::code
        SwaggerUI["Swagger UI Assets\n(swagger/ui/)"]:::external
        APISpec["API Spec Endpoint\n(swagger/swagger.yml)"]:::code
        SwaggerRouter --> EmbeddedSpec
        SwaggerRouter --> Operations
        SwaggerRouter --> SwaggerUI
        SwaggerRouter --> APISpec
    end

    %% Controller/Handler Layer
    Handler["Handlers\n(handlers/*.go)"]:::code
    SwaggerRouter --> Handler

    Handler --> Util
    Handler --> Models
    Handler --> Persistence
    Persistence --> Handler

    %% Domain Model Layer
    Models["Models\n(models/*.go)"]:::code

    %% Persistence Layer
    Persistence["Neo4j Adapter\n(neo4j/main.go)"]:::code
    Persistence --> Neo4jDB

    %% Database
    Neo4jDB[(Neo4j Database)]:::database
    Neo4jDB --> Persistence

    %% Utilities
    Util["Utilities\n(util/util.go)"]:::code

    %% Tooling (Off-diagram)
    subgraph "Tooling"
        Makefile["Makefile"]:::tooling
        Vendor["vendor/"]:::tooling
        SwaggerScripts["Swagger Scripts & Schema\n(swagger/)"]:::tooling
        Makefile --> Vendor
        Makefile --> SwaggerScripts
        SwaggerScripts --> APISpec
    end

    %% Codegen Step
    APISpec --> Operations
    APISpec --> Models

    %% Styling
    classDef code fill:#BBDEFB,stroke:#2196F3,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef database fill:#E1BEE7,stroke:#7B1FA2,stroke-width:1px
    classDef tooling fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px

    %% Click Events
    click SwaggerRouter "https://github.com/ccap-project/configmanager/blob/master/restapi/server.go"
    click EmbeddedSpec "https://github.com/ccap-project/configmanager/blob/master/restapi/embedded_spec.go"
    click Operations "https://github.com/ccap-project/configmanager/tree/master/restapi/operations/"
    click SwaggerUI "https://github.com/ccap-project/configmanager/tree/master/swagger/ui/"
    click APISpec "https://github.com/ccap-project/configmanager/blob/master/swagger/swagger.yml"
    click Handler "https://github.com/ccap-project/configmanager/tree/master/handlers/"
    click Models "https://github.com/ccap-project/configmanager/tree/master/models/"
    click Persistence "https://github.com/ccap-project/configmanager/blob/master/neo4j/main.go"
    click StaticUI "https://github.com/ccap-project/configmanager/blob/master/html/index.html"
    click StaticUI "https://github.com/ccap-project/configmanager/blob/master/html/root.js"
    click Main "https://github.com/ccap-project/configmanager/blob/master/cmd/config-manager-server/main.go"
    click Util "https://github.com/ccap-project/configmanager/blob/master/util/util.go"
    click Makefile "https://github.com/ccap-project/configmanager/tree/master/Makefile"
    click Vendor "https://github.com/ccap-project/configmanager/tree/master/vendor/"
    click SwaggerScripts "https://github.com/ccap-project/configmanager/tree/master/swagger/"
```
