# vmagautam/vma-cli architecture

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

- Interactive diagram: https://gitdiagram.com/vmagautam/vma-cli
- Repository: https://github.com/vmagautam/vma-cli

## Overview

##### Project Type and Purpose
- This is a command-line, full-stack “deployment orchestration” tool written in Python.
- Purpose: manage multi-tenant apps: clone repos, generate per-tenant Docker Compose stacks (backend, frontend, nginx), configure env vars, view logs, list GitHub repos, etc.

##### Directories
- vma/cli.py          → CLI entrypoint (Click-based commands)
- vma/commands/       → individual commands (deploy-backend, logs, list-github-repos, etc.)
- vma/core/           → plugin registration & core orchestration logic
- vma/plugins/        → extension points (e.g. nodejs support)
- vma/config/         → global defaults (e.g. paths, template location)
- tenants/            → dynamically created subdirs per tenant, each containing:
- backend/       → application code clone
- frontend/      → application code clone
- config/        → tenant_config.yaml
- docker-compose.yml
- nginx.conf
- docs/, resources/   → supplementary documentation and assets

##### Extract Architectural Insights from README
- External dependencies: Docker & Docker Compose, Nginx, PostgreSQL, Redis, GitHub API
- Workflow overview:
CLI invocation → command parsing → plugin/core logic → shell out to Docker Compose & Git → generate tenant artifacts → start/stop services

##### Mapping Components & Interactions
a. Main Components
1. CLI Layer (User Terminal & vma/cli.py)
2. Command Handlers (vma/commands/*)
3. Core Orchestrator & Plugin Manager (vma/core/plugins.py)
4. Configuration (vma/config + tenant_config.yaml)
5. Tenant Deployments (Docker Compose stacks for each tenant)
6. External Services: GitHub API, Docker Engine, Docker Registry, Nginx, PostgreSQL, Redis
b. Relationships & Data Flow
- User issues `vma <command>` → CLI Layer
- CLI Layer routes to a Command Handler
- Command Handler may call Core Orchestrator
- Core Orchestrator loads plugins if needed (e.g. NodeJS build)
- Orchestrator clones repos, writes config, shells out to Docker Compose
- Docker Compose spins up containers for backend, frontend, nginx on tenant network
- Services talk internally (backend ↔ PostgreSQL/Redis, frontend ↔ backend API via nginx)
- CLI can query Docker logs or GitHub endpoints and return output to user
c. Architectural Patterns & Principles
- Plugin architecture for extensibility (core vs plugins)
- Multi-tenant isolation via separate Docker Compose stacks & networks
- Declarative configuration per tenant
- Single CLI binary orchestrating multiple subsystems
d. Key Technologies
- Python (Click for CLI)
- Docker & Docker Compose
- Nginx (reverse proxy)
- Git/GitHub API
- PostgreSQL, Redis

##### Detailed Capture—Don’t Overthink
- Distinct logical component (CLI, commands, plugins, orchestrator, config, containers)
- For multi‐tenant, show at least two tenant stacks side by side to illustrate isolation

- How a user command flows through the CLI into code modules
- How configuration is generated and consumed
- How Docker Compose brings up per-tenant containers and networking
- Where external services (GitHub, DB, Redis) fit into the picture
- The plugin architecture and extensibility points

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        direction TB
        Terminal["User Terminal"]:::external
        Terminal -->|"vma <command>"| CLI
    end

    %% Application Logic Layer
    subgraph "Application Logic"
        direction TB
        CLI["vma CLI"]:::python
        CLI -->|"routes to"| DeployBackend
        CLI -->|"routes to"| Logs
        CLI -->|"routes to"| GitHubCmd

        DeployBackend["Deploy-backend Command"]:::python
        Logs["Logs Command"]:::python
        GitHubCmd["List GitHub Repos Command"]:::python

        DeployBackend -->|calls| CoreOrch
        Logs -->|calls| CoreOrch
        GitHubCmd -->|calls| CoreOrch

        CoreOrch["Core Orchestrator"]:::python
        PluginMgr["Plugin Manager"]:::plugin
        CoreOrch -->|loads| PluginMgr
        PluginMgr -->|extends with| NodeJSPlugin

        NodeJSPlugin["NodeJS Plugin"]:::plugin
        CoreOrch -->|uses| Utils

        Utils["Shared Utilities"]:::python
    end

    %% Configuration & Artifacts Layer
    subgraph "Configuration & Artifacts"
        direction TB
        GlobalConfig["Global Config"]:::config
        CoreOrch -->|reads/writes| GlobalConfig

        TenantConfig["tenant_config.yaml"]:::config
        ComposeFile["docker-compose.yml"]:::config
        NginxConf["nginx.conf"]:::config

        CoreOrch -->|generates| TenantConfig
        CoreOrch -->|generates| ComposeFile
        CoreOrch -->|generates| NginxConf

        subgraph "Tenant Code Repos"
            direction TB
            BackendCode["backend/"]:::docker
            FrontendCode["frontend/"]:::docker
        end
        CoreOrch -->|clones| BackendCode
        CoreOrch -->|clones| FrontendCode
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        DockerEngine["Docker Engine"]:::external
        DockerEngine -->|runs| TenantStack1
        DockerEngine -->|runs| TenantStack2

        subgraph "Tenant: tenant1"
            direction TB
            TenantStack1["Tenant1 Stack"]:::docker
            TenantStack1 --> Backend1
            TenantStack1 --> Frontend1
            TenantStack1 --> Nginx1
        end

        subgraph "Tenant: tenant2"
            direction TB
            TenantStack2["Tenant2 Stack"]:::docker
            TenantStack2 --> Backend2
            TenantStack2 --> Frontend2
            TenantStack2 --> Nginx2
        end

        Backend1["Backend Container"]:::docker
        Frontend1["Frontend Container"]:::docker
        Nginx1["Nginx Container"]:::docker

        Backend2["Backend Container"]:::docker
        Frontend2["Frontend Container"]:::docker
        Nginx2["Nginx Container"]:::docker

        Backend1 -->|connects to| Postgres
        Backend1 -->|connects to| Redis
        Frontend1 -->|API calls via Nginx| Backend1

        Backend2 -->|connects to| Postgres
        Backend2 -->|connects to| Redis
        Frontend2 -->|API calls via Nginx| Backend2
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub API"]:::external
        DockerRegistry["Docker Registry"]:::external
        Postgres["PostgreSQL"]:::external
        Redis["Redis"]:::external
    end

    CLI -->|calls| GitHubAPI
    DockerEngine -->|pulls images| DockerRegistry

    %% Click Events
    click CLI "https://github.com/vmagautam/vma-cli/blob/dev/vma/cli.py"
    click DeployBackend "https://github.com/vmagautam/vma-cli/blob/dev/vma/commands/docker_logs.py"
    click Logs "https://github.com/vmagautam/vma-cli/blob/dev/vma/commands/logs.py"
    click GitHubCmd "https://github.com/vmagautam/vma-cli/blob/dev/vma/commands/github.py"
    click CoreOrch "https://github.com/vmagautam/vma-cli/blob/dev/vma/core/plugins.py"
    click GlobalConfig "https://github.com/vmagautam/vma-cli/blob/dev/vma/config/__init__.py"
    click TenantConfig "https://github.com/vmagautam/vma-cli/blob/dev/tenants/<tenant>/config/tenant_config.yaml"
    click ComposeFile "https://github.com/vmagautam/vma-cli/blob/dev/tenants/<tenant>/docker-compose.yml"
    click NginxConf "https://github.com/vmagautam/vma-cli/blob/dev/tenants/<tenant>/nginx.conf"
    click BackendCode "https://github.com/vmagautam/vma-cli/tree/dev/tenants/<tenant>/backend/"
    click FrontendCode "https://github.com/vmagautam/vma-cli/tree/dev/tenants/<tenant>/frontend/"
    click NodeJSPlugin "https://github.com/vmagautam/vma-cli/blob/dev/vma/plugins/nodejs/__init__.py"
    click Utils "https://github.com/vmagautam/vma-cli/blob/dev/vma/utils/__init__.py"

    %% Styles
    classDef python fill:#cde8ff,stroke:#6ea8fe,stroke-width:1px
    classDef plugin fill:#e4d1ff,stroke:#b59eff,stroke-width:1px
    classDef config fill:#d4f7d4,stroke:#6ecf6e,stroke-width:1px
    classDef docker fill:#ffd9b3,stroke:#ffa64d,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#999999,stroke-width:1pxatiem
```
