# msoares94/i-educar-ansible-playbook architecture

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

- Interactive diagram: https://gitdiagram.com/msoares94/i-educar-ansible-playbook
- Repository: https://github.com/msoares94/i-educar-ansible-playbook

## Overview

##### Project Type and Purpose
- This is an Infrastructure-as-Code (IaC) / configuration-management project written in Ansible.
- Its goal: fully automate installation and configuration of the i-Educar application (PHP/Nginx/PostgreSQL/Redis) across multiple environments (development, staging, production).

##### High-Level Architecture Components

A. Control Plane (Ansible Machine)
- Inventory & Hosts Definition
– inventory.ini (with host groups: [ieducar])
- Environment Variables
– group_vars/all/*.yml (global vars)
– group_vars/{development,staging,production}/main.yml
- Playbooks & Tasks
– playbook.yml (main orchestration)
– add-key.yml (SSH key bootstrap)
- Roles Directory
– roles/common
– roles/postgresql
– roles/redis-server
– roles/php-fpm
– roles/nginx
– roles/i-educar
– roles/i-educar-reports-package
– roles/i-educar-educacenso-package

B. Data Plane (Managed Servers)
- Ubuntu Server 22.04+ hosts in group [ieducar]
- On each host the playbook will install/configure:
– PostgreSQL (DB server)
– Redis (cache/session store)
– PHP-FPM (runtime for PHP app)
– NGINX (web server + reverse proxy)
– i-Educar application code & community packages
– SSL certificates (Let’s Encrypt via Certbot or provided certs)
– File permissions (ACLs)

##### Component Interactions & Data Flows
- Control Plane → Managed Nodes:
1) Ansible connects via SSH (inventory.ini / add-key.yml).
2) Loads group_vars based on target label (dev/staging/prod).
3) Executes playbook.yml → invokes roles in order:
common → postgresql → redis-server → php-fpm → nginx → i-educar → community packages
4) Each role runs tasks (create users, install packages, render templates, restart services).
- Within Managed Node:
- NGINX routes HTTP(S) → PHP-FPM
- PHP-FPM executes i-Educar code → interacts with PostgreSQL + Redis
- Certbot requests/renews SSL from Let’s Encrypt (if enabled)
- Templates (Jinja2) generate NGINX configs based on variables (domain, SSL flags)

##### Architectural Patterns & Principles
- Idempotent, role-based configuration management
- Environment-specific overrides via group_vars
- Modular roles each handling one concern (e.g., DB, cache, web, app)
- Handler notifications to restart/reload services only when needed
- Separation of concerns: network (SSH), orchestration (Ansible), provisioning (roles), application layer (i-Educar)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane" 
        INV["inventory.ini"]:::control
        subgraph "group_vars"
            A1["all/composer.yml"]:::control
            A2["all/ieducar.yml"]:::control
            A3["all/nginx.yml"]:::control
            A4["all/php-fpm.yml"]:::control
            A5["all/postgresql.yml"]:::control
            A6["all/system.yml"]:::control
            B1["development/main.yml"]:::control
            B2["staging/main.yml"]:::control
            B3["production/main.yml"]:::control
        end
        subgraph "Playbooks"
            P1["playbook.yml"]:::control
            P2["add-key.yml"]:::control
        end
        subgraph "Roles"
            R1["common"]:::control
            R2["postgresql"]:::control
            R3["redis-server"]:::control
            R4["php-fpm"]:::control
            R5["nginx"]:::control
            R6["i-educar"]:::control
            R7["i-educar-reports-package"]:::control
            R8["i-educar-educacenso-package"]:::control
        end
    end

    %% Data Plane
    subgraph "Data Plane ([ieducar] Hosts)"
        HOST["Ubuntu Server 22.04+"]:::data
        subgraph "Services on Host"
            DB["PostgreSQL"]:::data
            CACHE["Redis"]:::data
            PHP["PHP-FPM"]:::data
            WEB["NGINX"]:::data
            APP["i-Educar App"]:::data
            CP1["Reports Package"]:::data
            CP2["Educacenso Package"]:::data
            SSL["Certbot/SSL"]:::data
        end
    end

    %% External Services
    DNS["DNS/Domain"]:::external
    LE["Let's Encrypt CA"]:::external

    %% Connections
    INV -->|"SSH Inventory"| HOST
    P2 -->|"SSH add-key"| HOST
    P1 -->|"ansible-playbook"| HOST
    HOST --> DB
    HOST --> CACHE
    WEB --> PHP
    PHP --> DB
    PHP --> CACHE
    WEB --> SSL
    SSL -->|"ACME HTTP"| LE
    DNS --> WEB

    %% Click Events
    click INV "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/inventory.ini.example"
    click A1 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/all/composer.yml"
    click A2 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/all/ieducar.yml"
    click A3 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/all/nginx.yml"
    click A4 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/all/php-fpm.yml"
    click A5 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/all/postgresql.yml"
    click A6 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/all/system.yml"
    click B1 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/development/main.yml"
    click B2 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/staging/main.yml"
    click B3 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/group_vars/production/main.yml"
    click P1 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/playbook.yml"
    click P2 "https://github.com/msoares94/i-educar-ansible-playbook/blob/2.9/add-key.yml"
    click R1 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/common"
    click R2 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/postgresql"
    click R3 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/redis-server"
    click R4 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/php-fpm"
    click R5 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/nginx"
    click R6 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/i-educar"
    click R7 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/i-educar-reports-package"
    click R8 "https://github.com/msoares94/i-educar-ansible-playbook/tree/2.9/roles/i-educar-educacenso-package"

    %% Styles
    classDef control fill:#DDEBF7,stroke:#1F4E79,color:#000;
    classDef data fill:#E2EFDA,stroke:#397D02,color:#000;
    classDef external fill:#FCE4D6,stroke:#7F6000,color:#000
```
