Skip to content

Latest commit

 

History

History
208 lines (161 loc) · 5.77 KB

architecture.md

File metadata and controls

208 lines (161 loc) · 5.77 KB

🏗 Architecture — OpenPlayground

This document describes the internal architecture of OpenPlayground, explaining how the project is structured, how data flows through the application, and how different components work together to render the platform.

OpenPlayground is a static, frontend-only web application built with HTML, CSS, and JavaScript, designed to be lightweight, easy to contribute to, and suitable for hosting on platforms like GitHub Pages.

📌 Architectural Overview

  • Architecture Type: Static, component-based frontend
  • Rendering: Client-side rendering using JavaScript
  • Data Source: Centralized JSON file
  • Backend: None (as of now)

Core Principles

  • Beginner-friendly codebase
  • Clear separation of concerns
  • Reusable UI components
  • Simple contribution workflow
  • Zero setup required to run locally

📂 Directory Structure

OpenPlayground/
│
├── .github/                     # GitHub workflows, templates, configs
├── .vscode/                     # Editor configuration
│
├── components/                  # Reusable HTML components
│   ├── header.html
│   ├── footer.html
│   └── hero.html
│
├── css/                         # Stylesheets
│   ├── style.css                # Global styles
│   ├── theme.css                # Light/Dark theme styles
│   ├── responsive.css           # Responsive design rules
│   ├── footer.css
│   ├── about.css
│   ├── bookmarks.css
│   ├── contributor-cards.css
│   └── feedback.css
│
├── js/                          # JavaScript logic
│   ├── core/
│   │   └── app.js               # App bootstrap logic
│   │
│   ├── components.js            # Loads reusable HTML components
│   ├── projects-loader.js       # Loads and renders projects
│   ├── bookmarks.js             # Bookmark functionality
│   ├── bookmarks-page.js        # Bookmark page logic
│   ├── chatbot.js               # Chatbot interactions
│   ├── feedback.js              # Feedback handling
│   └── theme.js                 # Theme toggling logic
│
├── projects/                    # Project-related pages/assets
│
├── projects.json                # Central project data source
│
├── index.html                   # Home page
├── projects.html                # Projects listing page
├── contributors.html            # Contributors page
├── about.html
├── contact.html
├── feedback.html
├── bookmarks.html
├── chatbot.html
├── stats.html
├── sitemap.html
├── starterTemplate.html
│
├── logo.jpg
├── validate-links.js
│
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── DEBUGGING_GUIDE.md
└── LICENSE

🧩 Component-Based Structure

/components

Contains reusable UI sections such as:

  • header.html
  • footer.html
  • hero.html

These components are dynamically injected into pages using JavaScript to avoid duplication and maintain consistency across pages.

🎨 Styling Architecture (/css)

CSS files are modular and responsibility-based:

  • style.css → Base/global styles
  • theme.css → Dark/light mode theming
  • responsive.css → Mobile and tablet responsiveness
  • Page-specific CSS files (about, bookmarks, feedback, etc.)

This approach keeps styles clean and manageable.

⚙️ JavaScript Architecture (/js)

Core App Initialization

  • core/app.js
    • Entry point for initializing the app
    • Sets up shared behaviors and loads dependencies

Component Loader

  • components.js
    • Dynamically injects header, footer, and hero components into pages

Project Rendering

  • projects-loader.js
    • Fetches projects.json
    • Parses project data
    • Dynamically creates and inserts project cards into the DOM

Feature-Specific Logic

  • bookmarks.js → Save/remove bookmarked projects
  • bookmarks-page.js → Render bookmarked items
  • chatbot.js → Chatbot UI logic
  • feedback.js → Feedback form handling
  • theme.js → Theme toggle and persistence

📦 Data Layer (projects.json)

projects.json is the single source of truth for all showcased projects.

Each project entry typically contains:

  • Project title
  • Description
  • Tech stack
  • Category/tags
  • Live demo link
  • GitHub repository link
  • Preview image (optional)

This file is consumed by projects-loader.js to render projects dynamically.

🔄 Data Flow

  1. User opens a page (e.g., projects.html)
  2. components.js injects reusable UI components
  3. projects-loader.js fetches projects.json
  4. JavaScript parses project data
  5. Project cards are dynamically created
  6. Cards are rendered into the DOM
  7. Filters, bookmarks, and theme logic update UI in real time

🌐 Client-Side Only Rendering

  • No server or database
  • No authentication
  • All logic runs in the browser
  • Easy local preview (open index.html)
  • Ideal for GitHub Pages hosting

📈 Scalability & Future Improvements

The current architecture allows easy expansion:

Possible Enhancements

  • Backend API for dynamic project submission
  • Database instead of JSON
  • User authentication
  • Commenting and reactions
  • Analytics dashboard
  • Admin moderation panel

Summary

Layer Responsibility
HTML Page structure
CSS Styling & theming
JavaScript Logic & interactivity
JSON Project data
Components Reusable UI sections

OpenPlayground’s architecture prioritizes simplicity, clarity, and community contribution, making it an ideal platform for beginners and open-source collaboration.

Just tell me 🚀