# zara-te05/marga architecture

> Architecture diagram of the GitHub repository zara-te05/marga, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zara-te05/marga
- Repository: https://github.com/zara-te05/marga

## Overview

Marga versions database schema through reversible migrations: users create and share changes, then apply them to named environments with drift and risk checks. The principal path runs from the CLI through project files and the migrator to a database engine; the server provides shared repository history and environment reporting over an API, with a web front end. README documents additional branch databases, SQL console, interactive UI, and risk analysis. Edges reflect shown calls or README statements; unsampled capabilities are retained without guessed internal wiring.

Main entry points: [`internal/controladores/cli`](https://github.com/zara-te05/marga/tree/main/internal/controladores/cli) (Marga commands), [`internal/controladores/api/handlers.go`](https://github.com/zara-te05/marga/blob/main/internal/controladores/api/handlers.go) (REST API), [`internal/datos/migrador/migrador.go`](https://github.com/zara-te05/marga/blob/main/internal/datos/migrador/migrador.go) (Migration runner), [`cmd/marga-server/main.go`](https://github.com/zara-te05/marga/blob/main/cmd/marga-server/main.go) (Marga server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["CLI workflows"]
  node_cli["Marga commands"]
  node_project["Project migrations<br/>[proyecto.go]"]
  node_git["Local Git<br/>[gitlocal.go]"]
  node_branchdb["Branch databases<br/>[ramabd.go]"]
  node_remote["Remote API client<br/>[remoto.go]"]
end

subgraph group_database["Migration runtime"]
  node_migrator["Migration runner<br/>[migrador.go]"]
  node_engine["Database engine"]
  node_pgread["Schema reader<br/>[leer.go]"]
  node_sqlgen["Migration SQL generator<br/>[generar_objetos.go]"]
  node_targetdb[("User database")]
end

subgraph group_server["Shared service"]
  node_server["Marga server<br/>[main.go]"]
  node_api["REST API<br/>[handlers.go]"]
  node_store[("History and repository store<br/>[commits.go]")]
  node_serverdb[("Server PostgreSQL<br/>[database.go]")]
  node_security["Authentication security<br/>[security.go]"]
end

subgraph group_domain["Domain logic"]
  node_models["Schema and diffs"]
  node_risk["SQL risk analysis<br/>[riesgo.go]"]
  node_checksum["Migration checksums<br/>[checksum.go]"]
end

subgraph group_presentation["User interfaces"]
  node_web["Web dashboard"]
  node_terminal["Terminal themes"]
  node_ui["Interactive UI<br/>[ui_vista.go]"]
  node_sqlconsole["SQL console<br/>[sqlconsola.go]"]
end

node_user(("Engineer"))
node_browser(("Browser user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"reads migrations"| node_project
node_cli -->|"applies changes"| node_migrator
node_migrator -->|"loads migrations"| node_project
node_migrator -->|"uses engine"| node_engine
node_migrator -->|"records and applies"| node_targetdb
node_engine -->|"reads schema"| node_pgread
node_cli -->|"generates migration"| node_sqlgen
node_sqlgen -->|"uses schema model"| node_models
node_cli -->|"checks SQL risk"| node_risk
node_cli -->|"syncs history"| node_remote
node_remote -->|"sends API requests"| node_api
node_server -->|"serves routes"| node_api
node_server -->|"opens database"| node_serverdb
node_server -->|"creates store"| node_store
node_store -->|"stores history"| node_serverdb
node_api -->|"handles repository data"| node_store
node_api -->|"checks credentials"| node_security
node_api -->|"serves front end"| node_web
node_browser -->|"uses dashboard API"| node_api
node_cli -->|"reads branch state"| node_git
node_cli -->|"manages branch databases"| node_branchdb
node_cli -->|"opens interactive UI"| node_ui
node_ui -->|"renders themes"| node_terminal
node_cli -->|"opens SQL console"| node_sqlconsole
node_cli -->|"checks migration identity"| node_checksum

click node_cli "https://github.com/zara-te05/marga/tree/main/internal/controladores/cli"
click node_project "https://github.com/zara-te05/marga/blob/main/internal/datos/proyecto/proyecto.go"
click node_git "https://github.com/zara-te05/marga/blob/main/internal/datos/gitlocal/gitlocal.go"
click node_branchdb "https://github.com/zara-te05/marga/blob/main/internal/datos/ramabd/ramabd.go"
click node_migrator "https://github.com/zara-te05/marga/blob/main/internal/datos/migrador/migrador.go"
click node_engine "https://github.com/zara-te05/marga/tree/main/internal/datos/motor"
click node_pgread "https://github.com/zara-te05/marga/blob/main/internal/datos/motor/postgres/leer.go"
click node_sqlgen "https://github.com/zara-te05/marga/blob/main/internal/datos/motor/postgres/generar_objetos.go"
click node_models "https://github.com/zara-te05/marga/tree/main/internal/modelos/esquema"
click node_risk "https://github.com/zara-te05/marga/blob/main/internal/modelos/riesgo/riesgo.go"
click node_checksum "https://github.com/zara-te05/marga/blob/main/internal/modelos/checksum/checksum.go"
click node_remote "https://github.com/zara-te05/marga/blob/main/internal/datos/remoto/remoto.go"
click node_server "https://github.com/zara-te05/marga/blob/main/cmd/marga-server/main.go"
click node_api "https://github.com/zara-te05/marga/blob/main/internal/controladores/api/handlers.go"
click node_store "https://github.com/zara-te05/marga/blob/main/internal/datos/store/commits.go"
click node_serverdb "https://github.com/zara-te05/marga/blob/main/internal/datos/database/database.go"
click node_security "https://github.com/zara-te05/marga/blob/main/internal/servicios/security/security.go"
click node_web "https://github.com/zara-te05/marga/tree/main/internal/vistas/web"
click node_terminal "https://github.com/zara-te05/marga/tree/main/internal/vistas/terminal"
click node_ui "https://github.com/zara-te05/marga/blob/main/internal/controladores/cli/ui_vista.go"
click node_sqlconsole "https://github.com/zara-te05/marga/blob/main/internal/controladores/cli/sqlconsola.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_project,node_git,node_branchdb,node_remote,node_browser toneBlue
class node_migrator,node_engine,node_pgread,node_sqlgen,node_targetdb toneAmber
class node_server,node_api,node_store,node_serverdb,node_security toneMint
class node_models,node_risk,node_checksum toneRose
class node_web,node_terminal,node_ui,node_sqlconsole,node_user toneIndigo
```

## Components

### CLI workflows

- [Marga commands](https://github.com/zara-te05/marga/tree/main/internal/controladores/cli): `internal/controladores/cli`
- [Project migrations](https://github.com/zara-te05/marga/blob/main/internal/datos/proyecto/proyecto.go): `internal/datos/proyecto/proyecto.go`
- [Local Git](https://github.com/zara-te05/marga/blob/main/internal/datos/gitlocal/gitlocal.go): `internal/datos/gitlocal/gitlocal.go`
- [Branch databases](https://github.com/zara-te05/marga/blob/main/internal/datos/ramabd/ramabd.go): `internal/datos/ramabd/ramabd.go`
- [Remote API client](https://github.com/zara-te05/marga/blob/main/internal/datos/remoto/remoto.go): `internal/datos/remoto/remoto.go`

### Migration runtime

- [Migration runner](https://github.com/zara-te05/marga/blob/main/internal/datos/migrador/migrador.go): `internal/datos/migrador/migrador.go`
- [Database engine](https://github.com/zara-te05/marga/tree/main/internal/datos/motor): `internal/datos/motor`
- [Schema reader](https://github.com/zara-te05/marga/blob/main/internal/datos/motor/postgres/leer.go): `internal/datos/motor/postgres/leer.go`
- [Migration SQL generator](https://github.com/zara-te05/marga/blob/main/internal/datos/motor/postgres/generar_objetos.go): `internal/datos/motor/postgres/generar_objetos.go`
- **User database**

### Shared service

- [Marga server](https://github.com/zara-te05/marga/blob/main/cmd/marga-server/main.go): `cmd/marga-server/main.go`
- [REST API](https://github.com/zara-te05/marga/blob/main/internal/controladores/api/handlers.go): `internal/controladores/api/handlers.go`
- [History and repository store](https://github.com/zara-te05/marga/blob/main/internal/datos/store/commits.go): `internal/datos/store/commits.go`
- [Server PostgreSQL](https://github.com/zara-te05/marga/blob/main/internal/datos/database/database.go): `internal/datos/database/database.go`
- [Authentication security](https://github.com/zara-te05/marga/blob/main/internal/servicios/security/security.go): `internal/servicios/security/security.go`

### Domain logic

- [Schema and diffs](https://github.com/zara-te05/marga/tree/main/internal/modelos/esquema): `internal/modelos/esquema`
- [SQL risk analysis](https://github.com/zara-te05/marga/blob/main/internal/modelos/riesgo/riesgo.go): `internal/modelos/riesgo/riesgo.go`
- [Migration checksums](https://github.com/zara-te05/marga/blob/main/internal/modelos/checksum/checksum.go): `internal/modelos/checksum/checksum.go`

### User interfaces

- [Web dashboard](https://github.com/zara-te05/marga/tree/main/internal/vistas/web): `internal/vistas/web`
- [Terminal themes](https://github.com/zara-te05/marga/tree/main/internal/vistas/terminal): `internal/vistas/terminal`
- [Interactive UI](https://github.com/zara-te05/marga/blob/main/internal/controladores/cli/ui_vista.go): `internal/controladores/cli/ui_vista.go`
- [SQL console](https://github.com/zara-te05/marga/blob/main/internal/controladores/cli/sqlconsola.go): `internal/controladores/cli/sqlconsola.go`

### Other components

- **Engineer**
- **Browser user**

## Connections

- Engineer → Marga commands: runs commands
- Marga commands → Project migrations: reads migrations (evidence: `internal/controladores/cli/migrar.go`)
- Marga commands → Migration runner: applies changes (evidence: `internal/controladores/cli/migrar.go`)
- Migration runner → Project migrations: loads migrations (evidence: `internal/datos/migrador/migrador.go`)
- Migration runner → Database engine: uses engine (evidence: `internal/datos/migrador/migrador.go`)
- Migration runner → User database: records and applies (evidence: `internal/datos/migrador/migrador.go`)
- Database engine → Schema reader: reads schema (evidence: `internal/datos/motor/motor.go`)
- Marga commands → Migration SQL generator: generates migration
- Migration SQL generator → Schema and diffs: uses schema model (evidence: `internal/datos/motor/postgres/generar_objetos.go`)
- Marga commands → SQL risk analysis: checks SQL risk (evidence: `internal/controladores/cli/migrar.go`)
- Marga commands → Remote API client: syncs history
- Remote API client → REST API: sends API requests
- Marga server → REST API: serves routes (evidence: `cmd/marga-server/main.go`)
- Marga server → Server PostgreSQL: opens database (evidence: `cmd/marga-server/main.go`)
- Marga server → History and repository store: creates store (evidence: `cmd/marga-server/main.go`)
- History and repository store → Server PostgreSQL: stores history
- REST API → History and repository store: handles repository data (evidence: `internal/controladores/api/handlers.go`)
- REST API → Authentication security: checks credentials (evidence: `internal/controladores/api/handlers.go`)
- REST API → Web dashboard: serves front end
- Browser user → REST API: uses dashboard API
- Marga commands → Local Git: reads branch state (evidence: `internal/controladores/cli/ramasbd.go`)
- Marga commands → Branch databases: manages branch databases
- Marga commands → Interactive UI: opens interactive UI
- Interactive UI → Terminal themes: renders themes (evidence: `internal/controladores/cli/ui_vista.go`)
- Marga commands → SQL console: opens SQL console
- Marga commands → Migration checksums: checks migration identity
