# jorgehernanvalencia/gaea architecture

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

- Interactive diagram: https://gitdiagram.com/jorgehernanvalencia/gaea
- Repository: https://github.com/jorgehernanvalencia/gaea

## Overview

##### Project type and purpose
- Documentation and glossaries (/docs)
- Proposals and drafts (/propuestas)
- Practical cases and examples (/casos)
- Reference materials (/recursos)
- “Herramientas” sub-apps (e.g., foro-lite PHP forums, local participation maps)
It is not a monolithic full-stack app but rather a content repository plus several lightweight PHP tools, all delivered as static or server-side rendered pages.

##### File structure
- Top-level directories:
- assets: logos, screenshots, illustrations
- docs, propuestas, casos, recursos: Markdown content
- herramientas: self-contained mini-apps (each with its own README, PHP, CSS, SQLite or file-based storage)
- No heavy build scripts or container definitions present; likely uses a static site generator or direct Markdown-to-HTML pipeline for docs and an Apache/PHP host for the tools.
- Configuration files are minimal (no package.json, no Dockerfiles)—this is primarily a GitHub-driven content repo with PHP sub-apps.

##### Key insights from the README
- Two public sites: https://gaea.fadcoad.com and https://logos.fadcoad.com
- Community contributions via GitHub Discussions
- MIT-licensed code, CC-BY-4.0 for docs
- Purpose: collaboratively build ethical algorithmic governance frameworks, policies, tools, and case studies.

##### Main components & their interactions
a. Source & Collaboration
- Developers and contributors push Markdown and PHP code into the GitHub repo.
- GitHub Discussions handles conversations (external service).
b. CI/CD / Build & Deployment
- A CI pipeline (e.g., GitHub Actions) picks up changes:
- Converts Markdown (/docs, /casos, /propuestas, /recursos) into static HTML (via Hugo/Jekyll or a custom script).
- Packages each herramienta sub-app for deploy.
- Artifacts are deployed to hosting infrastructure.
c. Hosting & Delivery
- Static site host (could be GitHub Pages, Netlify, or a VM) serves the compiled documentation site and assets via a CDN.
- A web server with PHP and SQLite (for foro-lite versions) serves the tools under /herramientas/*.
d. End Users
- Access docs, proposals, resources, and tools in a browser.
- For tools: user interactions (e.g., forum posts) go to PHP scripts which read/write a local SQLite DB or file store.
e. External services
- GitHub Discussions for community dialogue.
- Potential analytics, search indexing, or third-party integrations (not present in the repo but common in docs sites).

##### Architectural patterns and design principles
- Content-as-Code: Markdown files in Git drive the docs site.
- Micro-frontend-style tools: each herramienta is self-contained with its own assets, code, and storage.
- Static-First: most content is prebuilt and cached, minimizing server load.
- Minimal Server-Side Components: PHP+SQLite only where interactivity is needed (forums, participatory maps).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository and Content
    subgraph "GitHub Repository" 
        direction TB
        StaticAssets["Static Assets"]:::repo
        DocumentationContent["Documentation Content"]:::repo
        CaseStudies["Case Studies"]:::repo
        ProposalsDrafts["Proposals & Drafts"]:::repo
        RefMaterials["Reference Materials"]:::repo
        HerramientasContainer["Herramientas (Micro-apps)"]:::repo
    end

    %% Herramientas sub-apps
    subgraph "Herramientas Apps"
        direction TB
        ConsultaTool["Agile Collective Consultation"]:::repo
        SharedGovernanceTool["Shared Governance Matrix"]:::repo
        ForumLite01["Forum Lite v0.1"]:::repo
        ForumLite10["Forum Lite v1.0"]:::repo
        MapTool["Local Participation Map"]:::repo
        DecisionsMatrix["Collective Decisions Matrix"]:::repo
        Dashboard["Monitoring Dashboard"]:::repo
    end

    %% CI/CD and Build
    CI["GitHub Actions / CI"]:::ci
    SSG["Static Site Generator"]:::build
    Packaging["Package Herramientas"]:::build

    %% Hosting and Runtime
    StaticHosting["Static Hosting / CDN"]:::hosting
    PHPServer["PHP Web Server"]:::runtime
    DB[(SQLite DB)]:::runtime

    %% External and Users
    User["End User"]:::user
    Discussions["GitHub Discussions"]:::external
    Contributors["Contributors"]:::user

    %% Connections
    StaticAssets --> CI
    DocumentationContent --> CI
    CaseStudies --> CI
    ProposalsDrafts --> CI
    RefMaterials --> CI
    HerramientasContainer --> CI

    CI -->|"build docs"| SSG
    CI -->|"package herramientas"| Packaging

    Packaging --> PHPServer
    SSG -->|"deploy HTML"| StaticHosting

    PHPServer --> DB
    DB --> PHPServer

    User -->|"HTTP GET"| StaticHosting
    User -->|"HTTP GET/POST"| PHPServer

    Contributors <--> Discussions

    %% Group Herramientas contents into container
    HerramientasContainer --> ConsultaTool
    HerramientasContainer --> SharedGovernanceTool
    HerramientasContainer --> ForumLite01
    HerramientasContainer --> ForumLite10
    HerramientasContainer --> MapTool
    HerramientasContainer --> DecisionsMatrix
    HerramientasContainer --> Dashboard

    %% Click Events
    click StaticAssets "https://github.com/jorgehernanvalencia/gaea/tree/main/assets/"
    click DocumentationContent "https://github.com/jorgehernanvalencia/gaea/tree/main/docs/"
    click CaseStudies "https://github.com/jorgehernanvalencia/gaea/tree/main/casos/"
    click ProposalsDrafts "https://github.com/jorgehernanvalencia/gaea/tree/main/propuestas/"
    click RefMaterials "https://github.com/jorgehernanvalencia/gaea/tree/main/recursos/"
    click HerramientasContainer "https://github.com/jorgehernanvalencia/gaea/tree/main/herramientas/"
    click ConsultaTool "https://github.com/jorgehernanvalencia/gaea/blob/main/herramientas/consulta-colectiva-agil/README.md"
    click SharedGovernanceTool "https://github.com/jorgehernanvalencia/gaea/blob/main/herramientas/cuadro-gobernanza-compartida/README.md"
    click ForumLite01 "https://github.com/jorgehernanvalencia/gaea/tree/main/herramientas/foro/foro-lite-0.1/"
    click ForumLite10 "https://github.com/jorgehernanvalencia/gaea/tree/main/herramientas/foro/foro-lite-1.0/"
    click MapTool "https://github.com/jorgehernanvalencia/gaea/blob/main/herramientas/mapa-participacion-local/RRADME.md"
    click DecisionsMatrix "https://github.com/jorgehernanvalencia/gaea/blob/main/herramientas/matriz-decisiones-colectivas/README.md"
    click Dashboard "https://github.com/jorgehernanvalencia/gaea/blob/main/herramientas/tablero-seguimiento/README.md"
    click StaticAssets "https://github.com/jorgehernanvalencia/gaea/tree/main/assets/"

    %% Styles
    classDef repo fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef ci fill:#E0F7FA,stroke:#00acc1,color:#006064;
    classDef build fill:#FFF3E0,stroke:#fb8c00,color:#e65100;
    classDef hosting fill:#E8F5E9,stroke:#43a047,color:#1b5e20;
    classDef runtime fill:#FFF3E0,stroke:#fb8c00,color:#e65100;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#455A64;
    classDef user fill:#F3E5F5,stroke:#8e24aa,color:#4A148C;
```
