# marcosd4h/mdmatador architecture

> Architecture diagram of the GitHub repository marcosd4h/mdmatador, 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/marcosd4h/mdmatador
- Repository: https://github.com/marcosd4h/mdmatador

## Overview

##### Project Type and Purpose
- MDMatador is a monolithic, full‑stack web application written in Go.
- It provides a web UI (HTML templates + CSS/JS assets) for administrators to enroll, manage, and issue commands to mobile devices (an MDM server).
- It persists data (users, enrollments, certificates, device settings, pending operations) in a SQL database via migration scripts.

##### High‑Level File Structure / Architectural Insights
- cmd/web: entrypoint Go code (main.go) that wires up HTTP server, routes, middleware, handlers.
- assets: all static resources (CSS, JS, fonts, images) and DB migration SQL.
- templates: HTML view templates (base, pages, partials).
- internal: core business logic modules:
- database: DB connection and data access (users, mdm tables).
- mdm: Apple MDM protocol handling (command manager, CSR generation, message types).
- token/password/validator: auth, credentials, request validation.
- request/response: HTTP request decoding and response encoding (JSON, templates, raw).
- version/common/helpers: utilities.
- go.mod / Makefile: build, test, migrate, run.

##### Key Components
a. Frontend Layer
- Web Browser (Admin UI)
- Static Assets Server (served by Go)
- HTML Templates Renderer
b. Backend Layer
- Go HTTP Server (cmd/web)
- Routing & Middleware (authentication, logging, error handling)
- Handler Functions (CRUD for users, devices, MDM operations)
- Business Modules (internal packages: mdm, token, validator, password)
c. Data Layer
- Relational Database (PostgreSQL / MySQL)
- Migration subsystem (assets/migrations)
d. External Services
- Apple Push Notification Service (APNs) for delivering MDM commands
- Enrolled Devices (iOS/Mac devices implementing MDM protocol)

##### Relationships and Data Flows
1. Admin interacts via Browser → sends HTTP requests to Go Server
2. Go Server:
- Serves static assets & renders templates
- Decodes JSON / form data via request/* packages
- Authorizes via token/password modules
- Validates via validator module
- Routes to appropriate handler (routes.go → handlers.go)
3. Handlers call internal/database to read/write schema tables
4. MDM handlers invoke internal/mdm to:
- Generate commands, build protocol messages
- Enqueue commands in pending_device_operations table
5. APNs Client in Go Server polls pending operations → pushes commands to devices via APNs
6. Devices consume commands and callback to Go Server’s MDM endpoints → processed again by internal/mdm modules
7. Updates persisted in DB; UI refreshed

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (templates/static), Application (handlers, middleware), Domain (internal modules), Persistence (database).
- MVC‑like: Templates + data models, Controllers = handlers.
- Single binary deployment: Go compiles into one executable.
- Dependency inversion: internal modules abstracted via interfaces (e.g., database/db.go).
- Migration‑driven schema management via assets/migrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph Client Layer
        Browser["Web Browser"]:::client
    end

    subgraph Backend Layer
        Entry["Entrypoint (main.go)"]:::server
        Setup["Server Setup (server.go)"]:::server
        Middleware["Routing & Middleware (middleware.go)"]:::server
        Routes["Routing (routes.go)"]:::server

        subgraph HTTP Request Handling
            RequestForms["Form Decoder"]:::server
            RequestJSON["JSON Decoder"]:::server
            RequestMDM["MDM Request Decoder"]:::server
            ResponseJSON["JSON Encoder"]:::server
            ResponseMDM["MDM Response Encoder"]:::server
            ResponseRaw["Raw Encoder"]:::server
            TemplatesRenderer["Template Renderer"]:::server
            HTMLTemplates["HTML Templates"]:::server
            StaticAssets["Static Assets Server"]:::server
        end

        subgraph HTTP Handlers
            HandlersCRUD["CRUD Handlers (handlers.go)"]:::server
            HandlersMDM["MDM Handlers (mdm.go)"]:::server
        end

        subgraph Business Logic Modules
            MDM["MDM Protocol (internal/mdm)"]:::logic
            Token["Auth Token Module"]:::logic
            Password["Password Module"]:::logic
            ValidatorCore["Validator (validator.go)"]:::logic
            ValidatorHelpers["Validator Helpers"]:::logic
            CommonHelpers["Common Helpers"]:::logic
            Funcs["Utility Funcs"]:::logic
            Version["Version Info"]:::logic
        end
    end

    subgraph Data Layer
        Database[(SQL Database)]:::db
        DBCore["DB Core (db.go)"]:::db
        DBUsers["Users Model"]:::db
        DBMDM["MDM Model"]:::db
        Migrations["Migrations"]:::db
    end

    subgraph External Services
        APNs["Apple Push Notification Service"]:::external
        Devices["Enrolled Devices"]:::external
    end

    %% Flows
    Browser -->|"HTTP GET/POST"| Entry
    Entry --> Setup
    Setup --> Middleware
    Middleware --> Routes
    Routes --> RequestForms
    Routes --> RequestJSON
    Routes --> RequestMDM
    RequestForms --> HandlersCRUD
    RequestJSON --> HandlersCRUD
    RequestMDM --> HandlersMDM
    HandlersCRUD --> ResponseJSON
    HandlersMDM --> ResponseMDM
    HandlersCRUD -->|render| TemplatesRenderer
    TemplatesRenderer --> HTMLTemplates
    HandlersCRUD -->|serve| StaticAssets
    ResponseJSON --> Browser
    ResponseMDM --> Browser

    HandlersCRUD --> DBCore
    HandlersCRUD --> DBUsers
    HandlersMDM --> DBMDM
    MDM --> DBMDM
    DBCore --> Database
    DBUsers --> Database
    DBMDM --> Database
    Migrations --> Database

    HandlersMDM --> MDM
    MDM -->|enqueue commands| DBMDM
    MDM -->|push commands| APNs
    APNs -->|deliver| Devices
    Devices -->|callbacks| Entry

    %% Click Events
    click StaticAssets "https://github.com/marcosd4h/mdmatador/tree/main/assets/static"
    click HTMLTemplates "https://github.com/marcosd4h/mdmatador/tree/main/assets/templates"
    click TemplatesRenderer "https://github.com/marcosd4h/mdmatador/blob/main/internal/response/templates.go"
    click Entry "https://github.com/marcosd4h/mdmatador/blob/main/cmd/web/main.go"
    click Setup "https://github.com/marcosd4h/mdmatador/blob/main/cmd/web/server.go"
    click Routes "https://github.com/marcosd4h/mdmatador/blob/main/cmd/web/routes.go"
    click Middleware "https://github.com/marcosd4h/mdmatador/blob/main/cmd/web/middleware.go"
    click HandlersCRUD "https://github.com/marcosd4h/mdmatador/blob/main/cmd/web/handlers.go"
    click HandlersMDM "https://github.com/marcosd4h/mdmatador/blob/main/cmd/web/mdm.go"
    click RequestForms "https://github.com/marcosd4h/mdmatador/blob/main/internal/request/forms.go"
    click RequestJSON "https://github.com/marcosd4h/mdmatador/blob/main/internal/request/json.go"
    click RequestMDM "https://github.com/marcosd4h/mdmatador/blob/main/internal/request/mdm.go"
    click ResponseJSON "https://github.com/marcosd4h/mdmatador/blob/main/internal/response/json.go"
    click ResponseMDM "https://github.com/marcosd4h/mdmatador/blob/main/internal/response/mdm.go"
    click ResponseRaw "https://github.com/marcosd4h/mdmatador/blob/main/internal/response/raw.go"
    click Token "https://github.com/marcosd4h/mdmatador/blob/main/internal/token/token.go"
    click Password "https://github.com/marcosd4h/mdmatador/blob/main/internal/password/hash.go"
    click ValidatorCore "https://github.com/marcosd4h/mdmatador/blob/main/internal/validator/validator.go"
    click ValidatorHelpers "https://github.com/marcosd4h/mdmatador/blob/main/internal/validator/helpers.go"
    click MDM "https://github.com/marcosd4h/mdmatador/blob/main/internal/mdm/command_manager.go"
    click DBCore "https://github.com/marcosd4h/mdmatador/blob/main/internal/database/db.go"
    click DBUsers "https://github.com/marcosd4h/mdmatador/blob/main/internal/database/users.go"
    click DBMDM "https://github.com/marcosd4h/mdmatador/blob/main/internal/database/mdm.go"
    click Migrations "https://github.com/marcosd4h/mdmatador/tree/main/assets/migrations"
    click CommonHelpers "https://github.com/marcosd4h/mdmatador/blob/main/internal/common/helpers.go"
    click Funcs "https://github.com/marcosd4h/mdmatador/blob/main/internal/funcs/funcs.go"
    click Version "https://github.com/marcosd4h/mdmatador/blob/main/internal/version/version.go"

    %% Styles
    classDef client fill:#bbbbbb,stroke:#333,stroke-width:1px
    classDef server fill:#aed6f1,stroke:#1f618d,stroke-width:1px
    classDef logic fill:#d5f5e3,stroke:#1e8449,stroke-width:1px
    classDef db fill:#abebc6,stroke:#148f77,stroke-width:1px
    classDef external fill:#f9e79f,stroke:#b7950b,stroke-width:1px
```
