# geopnr/postparc architecture

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

- Interactive diagram: https://gitdiagram.com/geopnr/postparc
- Repository: https://github.com/geopnr/postparc

## Overview

##### Project Type and Purpose
- This is a monolithic Symfony (v3-style) web application (“postparcV2”) with both:
- A server‐rendered UI (Twig templates under app/Resources/views and PostparcBundle)
- A REST API (PostparcApiBundle under src/PostparcApiBundle)
- It is packaged with Docker (Dockerfile, docker-compose.yml) for containerized deployment, includes Symfony console commands for batch jobs, and integrates with external email (SendInBlue), analytics (Piwik), and DKIM signing.

##### Main Architectural Components
- Clients
- Web browser – HTTP(S) requests for the UI
- API consumers – mobile apps or third‐party systems calling the REST endpoints
- Web Tier (Docker containers)
- Reverse proxy / web server (Nginx or Apache, configured in docker/000-default.conf)
- PHP-FPM (the Symfony application code under app/, src/, vendor/)
- Application Tier
- Symfony HTTP kernel (AppKernel, bundles, controllers, services)
- Twig view layer for HTML generation
- Symfony Console for batch/cron tasks (cleanups, imports, alerts)
- Data Tier
- Relational database (MySQL or PostgreSQL via Doctrine ORM)
- File system storage (web/files for PDFs, web/importModels)
- (Optional) Cache store – Redis or Memcached for sessions or metadata
- External Services
- SendInBlue API (mailing)
- DKIM library for email signing (src/PostparcBundle/Lib/DKIM)
- Piwik/Matomo analytics service

##### Relationships & Interactions
- Browser → (HTTPS) → Nginx → PHP-FPM → Symfony Controllers → Doctrine → DB → back to Controller → Twig → HTML → Browser
- API client → Nginx → PHP-FPM → PostparcApiBundle REST Controllers → Doctrine → DB → JSON → API client
- Cron/CLI → Symfony Console Commands → Doctrine → DB / file storage
- Symfony Services (UserConfigService, QrCodeService, PiwikStatsService) call external HTTP APIs (SendInBlue, Piwik)
- File uploads/downloads via web/files path, managed by VichUploaderBundle if configured

##### Architectural Patterns and Principles
- MVC pattern: Controllers (src/.../Controller), Models/Entities (src/.../Entity), Views (Twig templates)
- Bundle structure: logical separation of UI (PostparcBundle) vs API (PostparcApiBundle)
- Modular Composer-based dependencies (vendor/, Composer scripts)
- Containerization: one container for web, one for PHP, one for DB, orchestrated via docker-compose

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        classDef presentation fill:#D6E9FE,stroke:#4A90E2
        Browser["Web Browser"]:::presentation
        APIClient["API Consumer"]:::presentation
    end

    %% Docker Compose Orchestration
    DockerCompose["Docker Compose"]:::app
    click DockerCompose "https://github.com/geopnr/postparc/blob/main/docker-compose.yml"

    %% Application Layer / Docker Services
    subgraph "Application Layer / Docker Services"
        classDef app fill:#E2F7E1,stroke:#27AE60

        Nginx["Reverse Proxy / Web Server"]:::app
        click Nginx "https://github.com/geopnr/postparc/blob/main/docker/000-default.conf"

        PHPFPM["PHP-FPM / Symfony Container"]:::app
        click PHPFPM "https://github.com/geopnr/postparc/tree/main/Dockerfile"

        subgraph "Symfony Application"
            classDef symfony fill:#FDEBD0,stroke:#F39C12

            SymfonyApp["AppKernel & Bundles"]:::symfony
            click SymfonyApp "https://github.com/geopnr/postparc/blob/main/app/AppKernel.php"

            subgraph "UI Bundle"
                classDef ui fill:#FCF3CF,stroke:#F1C40F
                GlobalViews["Global Twig Views"]:::ui
                click GlobalViews "https://github.com/geopnr/postparc/tree/main/app/Resources/views/"
                UIBundleViews["UI Bundle Views"]:::ui
                click UIBundleViews "https://github.com/geopnr/postparc/tree/main/src/PostparcBundle/Resources/views/"
                UIEntities["UI Entities"]:::ui
                click UIEntities "https://github.com/geopnr/postparc/tree/main/src/PostparcBundle/Entity/"
                UIRepos["UI Repositories"]:::ui
                click UIRepos "https://github.com/geopnr/postparc/tree/main/src/PostparcBundle/Repository/"
            end

            subgraph "API Bundle"
                classDef api fill:#F5EEF8,stroke:#8E44AD
                APIControllers["REST API Controllers"]:::api
                click APIControllers "https://github.com/geopnr/postparc/tree/main/src/PostparcApiBundle/Controller/"
                APIEntities["API Entities"]:::api
                click APIEntities "https://github.com/geopnr/postparc/tree/main/src/PostparcApiBundle/Entity/"
                APIRouting["API Routing Config"]:::api
                click APIRouting "https://github.com/geopnr/postparc/blob/main/src/PostparcApiBundle/Resources/config/routing_rest.yml"
                APIRepos["API Repositories"]:::api
                click APIRepos "https://github.com/geopnr/postparc/tree/main/src/PostparcApiBundle/Repository/"
            end

        end

        CLIRunner["CLI / Cron Runner"]:::app
        click CLIRunner "https://github.com/geopnr/postparc/tree/main/bin/console"
        click CLIRunner "https://github.com/geopnr/postparc/tree/main/src/PostparcBundle/Command/"
    end

    %% Data Layer
    subgraph "Data Layer"
        classDef data fill:#FEF9E7,stroke:#F39C12
        DB["Relational Database"]:::data
        FileStorage["File Storage"]:::data
        click FileStorage "https://github.com/geopnr/postparc/tree/main/web/files/"
        ImportModels["Import Models"]:::data
        click ImportModels "https://github.com/geopnr/postparc/tree/main/web/importModels/"
        CacheStore["Cache Store (Redis/Memcached)"]:::data
    end

    %% External Services
    subgraph "External Services"
        classDef external fill:#F0F4F8,stroke:#34495E
        SendInBlue["SendInBlue API"]:::external
        click SendInBlue "https://github.com/geopnr/postparc/blob/main/src/PostparcBundle/Controller/SendInBlueController.php"
        click SendInBlue "https://github.com/geopnr/postparc/blob/main/app/Resources/views/sendInblue/index.html.twig"
        Piwik["Piwik Analytics"]:::external
        DKIMLib["DKIM Library"]:::external
        click DKIMLib "https://github.com/geopnr/postparc/tree/main/src/PostparcBundle/Lib/DKIM/"
    end

    %% Connections
    Browser -->|"HTTPS"| Nginx
    APIClient -->|"HTTP API"| Nginx
    Nginx -->|"FastCGI"| PHPFPM

    PHPFPM -->|"handles requests"| SymfonyApp
    SymfonyApp --> UIEntities
    SymfonyApp --> APIEntities

    SymfonyApp -->|"SQL"| DB
    SymfonyApp -->|"File I/O"| FileStorage
    SymfonyApp -->|"File I/O"| ImportModels
    SymfonyApp -->|"Cache"| CacheStore

    CLIRunner -->|"CLI"| SymfonyApp

    SymfonyApp -->|"SMTP/API"| SendInBlue
    SymfonyApp -->|"HTTP"| Piwik
    SymfonyApp -->|"Email Signing"| DKIMLib

    %% Styles
    class Browser,APIClient presentation
    class DockerCompose,Nginx,PHPFPM,CLIRunner app
    class SymfonyApp symfony
    class GlobalViews,UIBundleViews,UIEntities,UIRepos ui
    class APIControllers,APIEntities,APIRouting,APIRepos api
    class DB,FileStorage,ImportModels,CacheStore data
    class SendInBlue,Piwik,DKIMLib external
```
