Architecture

This document describes the PLift architecture with diagrams showing how components are connected and how data flows through the system.

System Overview

PLift uses a Salt Stack container to generate all configurations from YAML pillar files, which are then used by Docker Compose to orchestrate containers.

How It Works

1. Developer runs plift commands
2. PLift CLI reads configuration from configs/ and executes Salt
3. Salt Container generates configurations using Jinja2 templates
4. Docker Compose starts all containers using generated files

Generated Configurations

Output	Description
Docker Compose files	Container orchestration
Application .env files	Environment variables
HAProxy config	Load balancer routing
Prometheus config	Metrics scraping
Grafana dashboards	Pre-configured visualizations
SSL certificates	TLS for HTTPS

Component Types

Type	Examples
Services	MySQL, PostgreSQL, Redis, RabbitMQ, Kafka
Applications	Laravel, Django, Node.js, Java
Tools	Prometheus, Grafana, Tempo, Loki, Portainer

---

Data Flow

Request Flow

User → HAProxy (SSL) → Application → Database/Cache
                                  → Message Queue

1. User sends HTTPS request through HAProxy
2. HAProxy routes to appropriate application
3. Application queries databases and cache
4. Application may publish to message queues

Observability Flow

Application → Alloy Collector → Prometheus (metrics)
                             → Loki (logs)
                             → Tempo (traces)
                                    ↓
                                Grafana

Data Type	Source	Storage	Query Language
Metrics	/metrics endpoints	Prometheus	PromQL
Logs	Container stdout	Loki	LogQL
Traces	OTLP protocol	Tempo	TraceQL

---

Configuration Generation

Input Files

File	Purpose
configs/services/init.sls	Service definitions
configs/tools/init.sls	Tool definitions
configs/apps/init.sls	Application definitions

Template Location

All Jinja2 templates are in salt/actions/generate/templates/:

• Docker Compose templates
• Application environment templates
• HAProxy configuration templates
• Prometheus configuration templates
• Grafana dashboard templates

Output Directory

Generated files are written to generated_configs/:

generated_configs/
├── docker/         # Docker Compose files
├── haproxy/        # HAProxy config
├── prometheus/     # Prometheus config
├── grafana/        # Dashboards & datasources
├── ssl/            # SSL certificates
└── migrations/     # Database migrations

---

Network Architecture

Port Mappings

Host Port	Service	Container Port
80, 443	HAProxy	80, 443
3000	Grafana	3000
9090	Prometheus	9090
8001	Portainer	9000
8978	DBeaver	8978
3307	MySQL	3306
5433	PostgreSQL	5432

Docker Network

All containers communicate via internal Docker network (plift_default) using service names.

Connection	Method
Browser → Services	Host port mapping
Apps → Databases	Internal network (service names)
Apps → Monitoring	Internal network
HAProxy → Apps	Internal network via lb_url

---

Monitoring Stack

Application Layer

Applications expose observability data:

Data	Endpoint	Format
Metrics	/metrics or /actuator/prometheus	Prometheus format
Logs	stdout	JSON
Traces	OTLP (4317/4318)	OpenTelemetry

Collection Layer

Collector	Function
Alloy	Collects logs, metrics, traces from containers
cAdvisor	Container resource metrics (CPU, memory, disk, network)

Storage Layer

System	Stores	Query Language
Prometheus	Metrics with timestamps	PromQL
Loki	Logs with labels	LogQL
Tempo	Traces and spans	TraceQL

Visualization

Grafana provides unified dashboards querying all three backends:

• Application Metrics Dashboard
• Application Logs Dashboard
• Application Traces Dashboard

---

Service Dependencies

Startup Order

Order	Layer	Services
1	Base	Salt, HAProxy, MySQL, Redis
2	Database	PostgreSQL
3	Message Queue	Zookeeper, then Kafka
4	Application	After databases are ready
5	Monitoring	Can start anytime
6	Admin Tools	Can start anytime

Dependencies

Service	Depends On
Kafka	Zookeeper
Laravel	MySQL, Redis
Django	PostgreSQL, Redis
Node.js	PostgreSQL, Redis
Java	PostgreSQL
Grafana	Prometheus, Loki, Tempo

Independent Services

Base layer services (Salt, HAProxy, MySQL, Redis, PostgreSQL) have no dependencies and can start independently.

---

Diagram Files

All architecture diagrams are SVG files in docs/images/:

Diagram	File
System Overview	architecture-overview.svg
Data Flow	data-flow.svg
Config Generation	config-generation.svg
Network Architecture	network-architecture.svg
Monitoring Stack	monitoring-stack.svg
Interaction Sequence	component-interaction-sequence.svg
Service Dependencies	service-dependencies.svg