How jaimeobregon/ladonacion works
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.