How jorgehernanvalencia/gaea works
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).