# pgomez-r/inception architecture

> Architecture diagram of the GitHub repository pgomez-r/inception, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pgomez-r/inception
- Repository: https://github.com/pgomez-r/inception

## Overview

##### Project type and purpose
- This is a Docker-based infrastructure project (“Inception”) whose goal is to containerize a WordPress stack (NGINX, PHP-FPM/WordPress, MariaDB) on a VM. It uses Docker Compose to define and link each service, enforces TLS, volumes for persistence, environment variables/secrets, and best-practice Docker patterns.

##### File structure
- Top level:
- Makefile – orchestrates build and deployment via `make`.
- README.md – project overview and instructions.
- srcs/ – all Docker-related sources and config.
– .env – environment variable definitions.
– docker-compose.yml – multi-container orchestration.
– requirements/ – per-service folders:
- mariadb/ (Dockerfile, conf/db.sh)
- nginx/ (Dockerfile, conf/nginx.conf)
- wordpress/ (Dockerfile, conf/wp-*.sh)
- No other code: this is pure ops/configuration; services communicate over a user-defined Docker network.
- Secrets are kept out of srcs (in a separate secrets/ directory referenced in README).

##### README for additional insights
- Services and requirements:
- NGINX container (TLSv1.2/1.3 only) as the sole public entry point on port 443.
- WordPress + PHP-FPM container (no embedded NGINX).
- MariaDB container (no web server).
- Two named volumes (DB data, WordPress files).
- A custom Docker network.
- Environment variables via .env and Docker secrets.
- Automatic restart policy on container crashes.
- Must use Alpine or Debian base images, no prebuilt service images.

a. Main components
- External Client (browser)
- Docker Host / VM
- Docker Network (overlay or bridge)
- Secret store / .env
- NGINX container
- WordPress+PHP-FPM container
- MariaDB container
- Two Docker Volumes (db_data, wp_data)
- Makefile & Docker-Compose (build orchestrator)
b. Relationships and interactions
1. Client → HTTPS (port 443) → NGINX
2. NGINX → HTTP internal → WordPress/PHP-FPM
3. WordPress/PHP-FPM → SQL queries → MariaDB
4. MariaDB ↔ Volume “db_data” for persistence
5. WordPress/PHP-FPM ↔ Volume “wp_data” for website files
6. Each container reads environment variables from .env or Docker secrets on startup
7. Makefile invokes docker-compose, builds each Dockerfile in requirements/ and brings up the network
c. Architectural patterns and design principles
- Micro-service style: one process per container
- Immutable infrastructure: containers built fresh from Dockerfiles
- Single responsibility: NGINX only handles TLS/HTTP proxy, PHP-FPM only processes PHP, DB only stores data
- Twelve-factor app compliance: config in env, stateless containers, separate build and run stages
d. Key technologies/frameworks
- Docker, Docker Compose
- Alpine/Debian base images
- NGINX with TLS config (nginx.conf)
- PHP-FPM (in WordPress container)
- MariaDB
- Volumes and custom bridge network
- Makefile for scripting `docker-compose up --build`
- .env file and Docker secrets for credentials

##### Elements
- Blue for “entry point” (NGINX)
- Green for “application” (WordPress)
- Orange for “database” (MariaDB)
- Gray for “orchestration/config” (Makefile, .env, secrets)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client (Browser)"]:::external

    %% Orchestration / Documentation
    subgraph "Orchestration & Config" 
        direction TB
        Make["Makefile"]:::orchestration
        Compose["docker-compose.yml"]:::orchestration
        Env[".env & Docker Secrets"]:::config
        README["README.md"]:::documentation
        Guide["guide/"]:::documentation
        Requirements["Service Requirements Directory"]:::documentation
    end

    %% Docker Host / VM
    subgraph "Docker Host / VM"
        direction TB
        subgraph "Docker Network: inception_net"
            direction TB
            NGINX["NGINX Container<br/>(TLSv1.2/1.3, port 443)"]:::frontdoor
            WP["WordPress + PHP-FPM Container"]:::application
            DB["MariaDB Container"]:::database
            VOLDB["db_data Volume"]:::volume
            VOLWP["wp_data Volume"]:::volume
        end
    end

    %% Flows
    Client -->|"HTTPS 443"| NGINX
    NGINX -->|"HTTP"| WP
    WP -->|"SQL Queries"| DB

    %% Volume Mounts
    VOLDB --> DB
    VOLWP --> WP

    %% Orchestration triggers
    Make --> Compose
    Compose --> NGINX
    Compose --> WP
    Compose --> DB

    %% Config injection
    Env --> NGINX
    Env --> WP
    Env --> DB

    %% Documentation references
    Make --- README
    README --- Guide
    Requirements --- Compose

    %% Click Events
    click Make "https://github.com/pgomez-r/inception/tree/main/Makefile"
    click Compose "https://github.com/pgomez-r/inception/blob/main/srcs/docker-compose.yml"
    click Env "https://github.com/pgomez-r/inception/blob/main/srcs/.env"
    click README "https://github.com/pgomez-r/inception/blob/main/README.md"
    click Guide "https://github.com/pgomez-r/inception/tree/main/guide/"
    click Requirements "https://github.com/pgomez-r/inception/tree/main/srcs/requirements"
    click NGINX "https://github.com/pgomez-r/inception/tree/main/srcs/requirements/nginx/Dockerfile"
    click NGINX "https://github.com/pgomez-r/inception/blob/main/srcs/requirements/nginx/conf/nginx.conf"
    click WP "https://github.com/pgomez-r/inception/tree/main/srcs/requirements/wordpress/Dockerfile"
    click WP "https://github.com/pgomez-r/inception/blob/main/srcs/requirements/wordpress/conf/wp-config.sh"
    click WP "https://github.com/pgomez-r/inception/blob/main/srcs/requirements/wordpress/conf/wp-setup.sh"
    click DB "https://github.com/pgomez-r/inception/tree/main/srcs/requirements/mariadb/Dockerfile"
    click DB "https://github.com/pgomez-r/inception/blob/main/srcs/requirements/mariadb/conf/db.sh"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ccc,stroke:#333
    classDef documentation fill:#ddd,stroke:#333
    classDef config fill:#bbb,stroke:#333
    classDef frontdoor fill:#bbdefb,stroke:#333
    classDef application fill:#c8e6c9,stroke:#333
    classDef database fill:#ffe0b2,stroke:#333
    classDef volume fill:#e1bee7,stroke:#333
```
