# redemapas/mapas architecture

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

- Interactive diagram: https://gitdiagram.com/redemapas/mapas
- Repository: https://github.com/redemapas/mapas

## Overview

##### Main Components Identification
a. Web Server / Request Routing:
- The public entry points are in the “public” folder (index.php, bootstrap.php) which ultimately call the core application bootstrap logic in “src/bootstrap.php”.
- The routing and request dispatching is managed via the “src/core/RoutesManager.php” and the controllers housed in “src/core/Controllers” and within each module.

b. Core Engine and Framework:
- “src/core” contains the core libraries including API classes, authentication providers, error handlers, cache, database connection (“src/core/Connection.php”) and other utilities.
- This layer implements an MVC pattern that separates controllers, models/entities and views/templates.

c. Modular/Plugin Architecture:
- Under “src/modules” are a large number of modules (e.g., Apps, FAQ, Home, LGPD, MailNotification, Opportunities, etc.) that encapsulate distinct features of the system. Each module typically has its own Controller.php, Module.php, configuration, templates, and assets.
- Plugins in “src/plugins” extend the core functionalities (e.g., authentication plugins, spam detectors).

d. Theming and Presentation Layer:
- Located under “src/themes”, this layer holds themes (such as BaseV1, BaseV2 and Subsite) that dictate the frontend look-and-feel.
- Themes include templates, assets (CSS, JavaScript, images), and layout definitions which directly correspond to what the end user sees.

e. Database and Persistence:
- The application uses a PostgreSQL database with PostGIS extensions. Configuration files for the database are in “config/db.php” and “dev/db/…” formats to support different environments.
- ORM and entity definitions are present in “src/core/Entities” and there is support for Doctrine mapping (see “src/core/DoctrineMappings/…”) indicating an ORM layer indexing the business objects.

f. Infrastructure and Deployment:
- Docker configuration files (“docker-compose.yml”, “docker/”, “dev/docker-compose.yml”) define containerized environments for development and production, clearly isolating application, database, and auxiliary services.
- CI/CD configurations appear in “.github/workflows” and “.travis.yml” files for automated testing and builds.

g. Tests & Continuous Integration:
- The “tests” directory contains automated tests for various modules and components ensuring that core functionalities (database, API, controllers, routing, etc.) work as intended.

##### Relationships and Interactions
- User requests enter through the public web server layer, then traverse the routing mechanism to hit the appropriate Controller within the core or specific module.
- Controllers use the core’s business logic (present in the “src/core” folder) and interact with the database via the ORM and raw queries (in “src/core/Connection.php”).
- When a module (e.g., Opportunities or Home) is invoked, it leverages its own controllers and views to generate dynamic content. These modules can also interact with one another (e.g., via shared entities, notifications, or widget integrations).
- Plugins and themes further enhance or customize the experience. Plugins inject extra authentication, caching, or UI components; themes organize the final HTML/CSS/JS rendering.
- Containerized deployment with Docker ensures that the web server, database, and background jobs (e.g., caching updates, scheduled jobs) run in isolated but interconnected services.

##### Architectural Patterns and Design Principles
- The project follows a modular, plugin-based, and MVC architecture where core functionality is separated from features packaged as modules.
- There is a strong emphasis on separation of concerns with a clear delineation between backend logic, business rules, and presentation layers.
- The system is environment-aware, having dedicated configuration directories (“config”, “dev/config.d”) and container orchestration scripts which facilitate both local development and production deployment.

##### Incorporating Relevant Technologies, Frameworks, and Libraries
- PHP (with Composer for dependency management) is the central backend language.
- PostgreSQL with PostGIS for geospatial capabilities.
- Docker for environment management along with Docker Compose.
- Frontend assets are managed with Node.js scripts and Sass (Ruby Sass gem) for CSS, as well as vendor libraries included within themes and modules.
- Testing frameworks and scripts (PHP unit tests, integration tests) are present.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    Client["Client Request"]:::client

    %% Public/Web Layer
    subgraph "Public/Web Layer"
        index["index.php"]
        bootstrapPub["bootstrap.php"]
    end

    %% Core Application Layer
    subgraph "Core Application"
        coreBootstrap["Bootstrap (src/bootstrap.php)"]
        routes["Routes Manager (src/core/RoutesManager.php)"]
        controllers["Controllers (src/core/Controllers)"]
        coreLib["Core Libraries (src/core)"]
    end

    %% Modules and Plugins
    subgraph "Modules & Plugins"
        modules["Modules (src/modules)"]
        plugins["Plugins (src/plugins)"]
    end

    %% Theming and Presentation Layer
    subgraph "Theming & Presentation"
        themes["Themes (src/themes)"]
    end

    %% Database and Persistence
    subgraph "Database & Persistence"
        db_config["DB Config (config/db.php)"]
        entities["Entities (src/core/Entities)"]
        doctrine["Doctrine Mappings (src/core/DoctrineMappings)"]
        database["PostgreSQL/PostGIS Database"]
    end

    %% Infrastructure and Deployment
    subgraph "Infrastructure"
        docker_compose["Docker Compose (docker-compose.yml)"]
        docker_folder["Docker Configs (docker/)"]
        dev_docker["Dev Docker Compose (dev/docker-compose.yml)"]
        cicd["CI/CD Workflows (.github/workflows, .travis.yml)"]
    end

    %% Testing and CI
    subgraph "Testing"
        tests["Automated Tests (tests)"]
    end

    %% Connections: Client to Public
    Client -->|"requests"| index
    Client -->|"requests"| bootstrapPub

    %% Public/Web Layer to Core Application
    index -->|"loads"| coreBootstrap
    bootstrapPub -->|"loads"| coreBootstrap

    %% Core Application internal flow
    coreBootstrap -->|"routes"| routes
    routes -->|"dispatches"| controllers
    controllers -->|"invokes"| coreLib

    %% Controllers interaction with Modules and Theming
    controllers -->|"calls"| modules
    controllers -->|"renders"| themes

    %% Core business logic interaction with Database
    coreLib -->|"uses"| entities
    entities -->|"maps to"| database
    coreLib -->|"uses"| doctrine

    %% Modules and Plugins interaction with Core
    modules -->|"extends"| coreLib
    plugins -->|"enhances"| coreLib

    %% Infrastructure supporting Public, Core and Database layers
    docker_compose --- index
    docker_compose --- coreLib
    docker_compose --- database
    docker_folder --- coreLib
    dev_docker --- coreLib
    cicd --- coreLib

    %% Testing integration
    tests --- coreLib

    %% Click Events
    click index "https://github.com/redemapas/mapas/blob/develop/public/index.php"
    click bootstrapPub "https://github.com/redemapas/mapas/blob/develop/public/bootstrap.php"
    click coreBootstrap "https://github.com/redemapas/mapas/blob/develop/src/bootstrap.php"
    click routes "https://github.com/redemapas/mapas/blob/develop/src/core/RoutesManager.php"
    click controllers "https://github.com/redemapas/mapas/tree/develop/src/core/Controllers"
    click coreLib "https://github.com/redemapas/mapas/tree/develop/src/core"
    click modules "https://github.com/redemapas/mapas/tree/develop/src/modules"
    click plugins "https://github.com/redemapas/mapas/tree/develop/src/plugins"
    click themes "https://github.com/redemapas/mapas/tree/develop/src/themes"
    click db_config "https://github.com/redemapas/mapas/blob/develop/config/db.php"
    click entities "https://github.com/redemapas/mapas/tree/develop/src/core/Entities"
    click doctrine "https://github.com/redemapas/mapas/tree/develop/src/core/DoctrineMappings"
    click docker_compose "https://github.com/redemapas/mapas/blob/develop/docker-compose.yml"
    click docker_folder "https://github.com/redemapas/mapas/tree/develop/docker/"
    click dev_docker "https://github.com/redemapas/mapas/blob/develop/dev/docker-compose.yml"
    click cicd "https://github.com/redemapas/mapas/tree/develop/.github/workflows"
    click tests "https://github.com/redemapas/mapas/tree/develop/tests/"

    %% Styles
    classDef client fill:#ffdead,stroke:#ff8c00,stroke-width:2px;
    classDef public fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef core fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef mod fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef theme fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef db fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef infra fill:#ffff99,stroke:#b15928,stroke-width:2px;
    classDef test fill:#e5c494,stroke:#a65628,stroke-width:2px;
    
    class Client client;
    class index,bootstrapPub public;
    class coreBootstrap,routes,controllers,coreLib core;
    class modules,plugins mod;
    class themes theme;
    class db_config,entities,doctrine,database db;
    class docker_compose,docker_folder,dev_docker,cicd infra;
    class tests test;
```
