# arthur-plazanet/ansible-projects architecture

> Architecture diagram of the GitHub repository arthur-plazanet/ansible-projects, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arthur-plazanet/ansible-projects
- Repository: https://github.com/arthur-plazanet/ansible-projects

## Overview

##### Project type and purpose
- This repository is a collection of personal Ansible projects—an Infrastructure-as-Code (IaC) toolkit—for automating server bootstrap, software installation, and monitoring on Ubuntu/Debian droplets.
- It is not a “traditional” application but rather an orchestration platform: playbooks, roles, inventories, templates, handlers, and CI workflows all live in one monorepo.

##### File structure
Top-level:
- .github/workflows/ansible-lint.yml → CI job to lint your Ansible code
- ansible.cfg, .gitignore, requirements.yml → repo-wide config
- roles/ → shared, reusable roles (common, nginx)
- projects/ → self-contained Ansible “projects,” each with its own playbooks, inventory, and roles

Under projects/:
- common/ → global playbooks and nginx setup, update+reboot tasks
- ubuntu_server_setup/ → playbooks, inventories, roles (ssh, ufw, user) to bootstrap a fresh Ubuntu server
- software/ → installs user-land software (zsh, prezto, nvm, Node/PM2, zellij, neovim); has its own roles & templates
- monitoring/ → role that gathers server metrics and software versions

##### README for additional insights
- Explains the multi-project structure, use cases, and example commands.
- Emphasizes reusability (common roles), per-project isolation, and Debian/Ubuntu focus.

a. Main components to model
- Developer/CI system (control node)
- GitHub repository (code & CI workflows)
- Ansible core (ansible-playbook, configuration, modules)
- Inventory files (per-project host definitions)
- Role library (shared roles vs project-specific roles)
- Templates and assets folder
- Remote target servers (Ubuntu droplets)
- External services (APT repos, NVM registry, Let’s Encrypt, etc.)

b. Relationships and data flows
1. Developer pushes code → GitHub
2. GitHub Actions lints playbooks/roles
3. Control node (local or CI) runs ansible-playbook:
– Loads ansible.cfg, inventory, variables, vault secrets
– Reads playbook YAML → imports roles, tasks, handlers, templates
– Opens SSH sessions to target servers
– Executes Ansible modules (apt, copy, template, shell, etc.)
4. Remote servers apply configuration, install software, configure nginx, set up monitoring agents
5. Servers may call external package registries (npm, apt), certificate authorities (Let’s Encrypt)

c. Architectural patterns/design principles
- Modular roles (each role has tasks/, handlers/, templates/)
- Multi-project directory layout: separate inventories & playbooks per project
- Common vs project-specific roles for reuse
- Handler pattern for service reloads
- CI-driven linting for quality enforcement

d. Key technologies/frameworks/libraries
- Ansible (core modules, inventory plugins)
- GitHub Actions (ansible-lint)
- Ubuntu/Debian package management (APT)
- NVM & npm registries
- Let’s Encrypt for SSL
- Jinja2 templating

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub & CI
    subgraph "GitHub & CI"
        GHRepo["GitHub Repository"]:::code
        CI["GitHub Actions CI"]:::process
    end

    %% Control Plane
    subgraph "Control Plane"
        ACN["Ansible Control Node"]:::process
        CFG["ansible.cfg"]:::code
        REQ["requirements.yml"]:::code
        GITIGNORE[".gitignore"]:::code
        README["README.md"]:::code
    end

    %% Shared Roles Library
    subgraph "Shared Roles Library"
        CommonRole["Common Role\nroles/common/tasks/main.yml"]:::code
        NginxTasks["Nginx Tasks\nroles/nginx/tasks/main.yml"]:::code
        NginxHandlers["Nginx Handlers\nroles/nginx/handlers/main.yml"]:::code
        NginxTemplate["Nginx Template\nroles/nginx/templates/nginx_server_block.j2"]:::code
    end

    %% Projects Container
    subgraph "Projects"
        direction TB
        subgraph "Common Project"
            PCCFG["ansible.cfg"]:::code
            SetupPB["nginx_setup_server_block.yml"]:::code
            UpdatePB["update_reboot_check.yml"]:::code
            Assets["assets/"]:::code
        end
        subgraph "Ubuntu Server Setup Project"
            USCFG["ansible.cfg"]:::code
            HostsEx["hosts.example.yaml"]:::code
            USPB["ubuntu_server_setup.yml"]:::code
            subgraph "Roles"
                SSHTasks["SSH Tasks\nroles/ssh/tasks/main.yml"]:::code
                SSHHandlers["SSH Handlers\nroles/ssh/handlers/main.yml"]:::code
                UFWTasks["UFW Tasks\nroles/ufw/tasks/main.yml"]:::code
                UserTasks["User Tasks\nroles/user/tasks/main.yml"]:::code
            end
        end
        subgraph "Software Installation Project"
            SWPB["install_user_softwares.yml"]:::code
            subgraph "Roles & Templates"
                ZshTasks["Zsh Tasks\nroles/zsh/tasks/main.yml"]:::code
                ZshInstall["install.yml"]:::code
                ZshPrezto["install_prezto.yml"]:::code
                NVMTasks["NVM/Node/PM2 Tasks\nroles/nvm_node_pm2/tasks/main.yml"]:::code
                NVMInstall["install.yml"]:::code
                NVMFind["find_current_npm_executable.yml"]:::code
                ZellijTasks["Zellij Tasks\nroles/zellij/tasks/main.yml"]:::code
                ZellijInstall["install_zellij.yml"]:::code
                NeovimTasks["Neovim Tasks\nroles/neovim/tasks/main.yml"]:::code
                NeovimInstall["install_neovim.yml"]:::code
                ZshTemplate[".zshrc.j2"]:::code
            end
        end
        subgraph "Monitoring Project"
            MPB["server_metrics.yml"]:::code
            MonTasks["Monitoring Tasks\nroles/monitoring/tasks/main.yml"]:::code
            MonMetrics["server_metrics.yml"]:::code
            MonVersions["software_versions.yml"]:::code
        end
    end

    %% Remote Servers
    subgraph "Remote Servers"
        Servers["Ubuntu Droplets"]:::remote
    end

    %% External Services
    subgraph "External Services"
        APT["APT Repositories"]:::external
        NPM["NPM Registry"]:::external
        LetsEncrypt["Let's Encrypt"]:::external
    end

    %% Connections
    Developer["Developer"]:::external
    Developer -->|"git push"| GHRepo
    GHRepo -->|"trigger"| CI
    CI -->|"lint playbooks"| ACN
    GHRepo --> ACN
    ACN --> CFG
    ACN --> REQ
    ACN --> GITIGNORE
    ACN --> README

    ACN -->|"load shared roles"| CommonRole
    ACN --> NginxTasks
    ACN --> NginxHandlers
    ACN --> NginxTemplate

    ACN --> PCCFG
    ACN --> SetupPB
    ACN --> UpdatePB
    ACN --> Assets

    ACN --> USCFG
    ACN --> HostsEx
    ACN --> USPB
    ACN --> SSHTasks
    ACN --> SSHHandlers
    ACN --> UFWTasks
    ACN --> UserTasks

    ACN --> SWPB
    ACN --> ZshTasks
    ACN --> ZshInstall
    ACN --> ZshPrezto
    ACN --> NVMTasks
    ACN --> NVMInstall
    ACN --> NVMFind
    ACN --> ZellijTasks
    ACN --> ZellijInstall
    ACN --> NeovimTasks
    ACN --> NeovimInstall
    ACN --> ZshTemplate

    ACN --> MPB
    ACN --> MonTasks
    ACN --> MonMetrics
    ACN --> MonVersions

    ACN -->|"ssh"| Servers
    Servers -->|"apt-get"| APT
    Servers -->|"npm install"| NPM
    Servers -->|"request cert"| LetsEncrypt

    %% Click Events
    click CI "https://github.com/arthur-plazanet/ansible-projects/blob/main/.github/workflows/ansible-lint.yml"
    click CFG "https://github.com/arthur-plazanet/ansible-projects/blob/main/ansible.cfg"
    click REQ "https://github.com/arthur-plazanet/ansible-projects/blob/main/requirements.yml"
    click GITIGNORE "https://github.com/arthur-plazanet/ansible-projects/blob/main/.gitignore"
    click README "https://github.com/arthur-plazanet/ansible-projects/blob/main/README.md"

    click CommonRole "https://github.com/arthur-plazanet/ansible-projects/blob/main/roles/common/tasks/main.yml"
    click NginxTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/roles/nginx/tasks/main.yml"
    click NginxHandlers "https://github.com/arthur-plazanet/ansible-projects/blob/main/roles/nginx/handlers/main.yml"
    click NginxTemplate "https://github.com/arthur-plazanet/ansible-projects/blob/main/roles/nginx/templates/nginx_server_block.j2"

    click PCCFG "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/common/ansible.cfg"
    click SetupPB "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/common/nginx_setup_server_block.yml"
    click UpdatePB "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/common/update_reboot_check.yml"
    click Assets "https://github.com/arthur-plazanet/ansible-projects/tree/main/projects/common/assets/"

    click USCFG "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/ansible.cfg"
    click HostsEx "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/inventories_example/hosts.example.yaml"
    click USPB "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/ubuntu_server_setup.yml"
    click SSHTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/roles/ssh/tasks/main.yml"
    click SSHHandlers "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/roles/ssh/handlers/main.yml"
    click UFWTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/roles/ufw/tasks/main.yml"
    click UserTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/ubuntu_server_setup/roles/user/tasks/main.yml"

    click SWPB "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/install_user_softwares.yml"
    click ZshTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/zsh/tasks/main.yml"
    click ZshInstall "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/zsh/install.yml"
    click ZshPrezto "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/zsh/install_prezto.yml"
    click NVMTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/nvm_node_pm2/tasks/main.yml"
    click NVMInstall "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/nvm_node_pm2/install.yml"
    click NVMFind "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/nvm_node_pm2/find_current_npm_executable.yml"
    click ZellijTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/zellij/tasks/main.yml"
    click ZellijInstall "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/zellij/install_zellij.yml"
    click NeovimTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/neovim/tasks/main.yml"
    click NeovimInstall "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/roles/neovim/install_neovim.yml"
    click ZshTemplate "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/software/templates/.zshrc.j2"

    click MPB "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/monitoring/server_metrics.yml"
    click MonTasks "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/monitoring/roles/monitoring/tasks/main.yml"
    click MonMetrics "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/monitoring/roles/monitoring/server_metrics.yml"
    click MonVersions "https://github.com/arthur-plazanet/ansible-projects/blob/main/projects/monitoring/roles/monitoring/software_versions.yml"

    %% Styles
    classDef code fill:#D0E6F5,stroke:#0366d6,color:#0366d6
    classDef process fill:#D5F5E3,stroke:#28a745,color:#28a745
    classDef remote fill:#FDEBD0,stroke:#d35400,color:#d35400
    classDef external fill:#F5EEF8,stroke:#6f42c1,color:#6f42c1
```
