# jaimeobregon/ladonacion architecture

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

- Interactive diagram: https://gitdiagram.com/jaimeobregon/ladonacion
- Repository: https://github.com/jaimeobregon/ladonacion

## Overview

##### Project Type and Purpose
- This project is a data-driven, interactive web application centered on investigative journalism. It presents rich visualizations (graphs, timelines, maps, document repositories) that expose details surrounding the 2012 donation from the Spanish Royal Household.
- The README emphasizes that the project’s software (UI, interactive visualizations) is completely decoupled from its data (documents, articles, entities, events). It serves as a framework that can be reused for investigating other stories by changing its data source.

##### File Structure
- There is a clear separation between:
- The user interface and static assets (located mostly under the “httpdocs” directory, containing HTML, JavaScript components, CSS, images, and other web resources).
- The data model and pipelines (found in the “data” directory with JSON5 files, schemas, and related information).
- The tools for processing, validating, and assembling the data (located in the “bin” directory with scripts like validate.js, screenshot.js, and configuration files).
- Other directories such as “slides” (for presentations) and a legacy-looking “321” folder provide additional content or versions.
- The use of modern web standards (ES6, web components, D3 for dynamic visualizations) is evident from the file names and the README’s technical overview.

##### Key Components
a. Data Pipeline & Data Model Building Components:
- /data: Contains raw data (articles, documents, entities, events, persons, places, relations, sources) in a structured format with accompanying JSON5 schemas.
- /bin: Holds JavaScript utilities for building, transforming, validating, and compiling the data model. These tools are used to generate the final dataset consumed by the front-end.
b. Presentation / Frontend Components:
- /httpdocs: The web-accessible folder serving as the main entry point for the application. It includes:
- HTML files (index.html, error.html)
- Assets (JavaScript libraries – with modular code including components built using modern JS standards, D3 visualizations, CSS stylesheets)
- Resources such as documents, images, articles, avatars – these are likely loaded dynamically by the application.
- /slides: Provides supplementary presentation materials and is likely used to explain or demonstrate the project externally.
c. External and Infrastructure Components:
- The static web server (serving files from httpdocs) is an essential external actor.
- The repository also integrates external services (like D3.js library for dynamic visualizations and links to social networks such as Twitter) which can be annotated.

##### Relationships and Interactions
- Data Flow:
- The “/bin” tools ingest and validate the structured data from “/data” (using the JSON5 schemas) and compile it into the final structure the application uses.
- The compiled data is then loaded by the browser-based application served from the “/httpdocs” directory.
- Component Interaction:
- The web UI (HTML + JavaScript) interacts with the data via dynamic client-side calls (possibly asynchronous, using modules defined under “httpdocs/assets/javascript”).
- The modular components (web components, D3 charts, and other interactive pieces) work together to display the four planes (network, timeline, map, documents) as described in the README.
- Deployment and update interactions are managed through GitHub workflows which trigger rsync jobs for production deployment.

##### Architectural Patterns and Design Principles
- The system is modular and decoupled. The separation of the data layer (“/data”, “/bin”) from the presentation layer (“/httpdocs”) is a key design principle.
- It adheres to modern web standards (ECMAScript modules, web components, shadow DOM) and leverages a component-based UI design, avoiding heavy frameworks.
- The static nature of the site and the use of client-side rendering highlight the simplicity and reusability of the application.

##### Final Recommendations
- Drill down into each layer showing key directories (e.g., /data, /bin, /httpdocs).
- External workflow (CI/CD and deployment through GitHub Actions and rsync).
- Annotations for technologies: ECMAScript 6, Web Components, D3.js, JSON5 data schemas.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        DataRepo("Data Repository") 
        DataTools("Data Processing Tools")
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        StaticWebApp("Static Web Application")
        JSComp("Interactive JS Components")
        JSMod("JS Modules")
    end

    %% Additional Resources
    subgraph "Additional Resources"
        PresMat("Presentation Materials")
        Legacy("Legacy/Alternate Content")
    end

    %% Deployment and External Services
    DeployPipe("Deployment Pipeline")
    ExtServices("External Services (D3.js,SocialNetworks)")

    %% Data Flow Connections
    DataRepo -->|"Validates&Compiles"| DataTools
    DataTools -->|"FeedsCompiledData"| StaticWebApp
    StaticWebApp -->|"Includes"| JSComp
    StaticWebApp -->|"Includes"| JSMod
    StaticWebApp -->|"Uses"| ExtServices
    DeployPipe -->|"DeploysViaRsync"| StaticWebApp
    StaticWebApp -->|"SuppliesContent"| PresMat
    StaticWebApp -->|"ProvidesLegacy"| Legacy

    %% Click Events
    click DataRepo "https://github.com/jaimeobregon/ladonacion/tree/main/data"
    click DataTools "https://github.com/jaimeobregon/ladonacion/tree/main/bin"
    click StaticWebApp "https://github.com/jaimeobregon/ladonacion/tree/main/httpdocs"
    click JSComp "https://github.com/jaimeobregon/ladonacion/tree/main/httpdocs/assets/javascript/components"
    click JSMod "https://github.com/jaimeobregon/ladonacion/tree/main/httpdocs/assets/javascript/modules"
    click DeployPipe "https://github.com/jaimeobregon/ladonacion/blob/main/.github/workflows/main.yml"
    click PresMat "https://github.com/jaimeobregon/ladonacion/tree/main/slides"
    click Legacy "https://github.com/jaimeobregon/ladonacion/tree/main/321"

    %% Styles
    classDef data fill:#AED6F1,stroke:#2471A3,stroke-width:2px
    classDef presentation fill:#A9DFBF,stroke:#239B56,stroke-width:2px
    classDef deployment fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px
    classDef resources fill:#F5CBA7,stroke:#C0392B,stroke-width:2px
    classDef external fill:#D7BDE2,stroke:#7D3C98,stroke-width:2px

    class DataRepo,DataTools data
    class StaticWebApp,JSComp,JSMod presentation
    class DeployPipe deployment
    class PresMat,Legacy resources
    class ExtServices external
```
