Skip to content

Documentation.md

Latest commit

 

History

History
109 lines (88 loc) · 6.21 KB

Documentation.md

File metadata and controls

109 lines (88 loc) · 6.21 KB
Raw

Technical Documentation & System Specifications

Project: UITS_Dev_Lab Single Page Application
Repository: oU1TS/dev
Tech Stack: Raw HTML5, Semantic CSS3, Vanilla ES6+ JavaScript

1. System Architecture & Design Principles

UITS_Dev_Lab is built as a lightweight, zero-dependency Single Page Application (SPA). It enforces strict separation of concerns across HTML structure, CSS styling tokens, JSON data representation, rendering logic, and application state control.

Core Architectural Pillars

  • Zero Third-Party Libraries: Built without external frameworks, bundlers, or UI component libraries to ensure instant page load and zero supply chain overhead.
  • Asynchronous Data Separation: All domain content (Roadmap steps, Setup Guides, Vault Resources, Grindset Leaderboard) is isolated in data.json and fetched dynamically at runtime.
  • Client-Side SPA Routing: Navigation is managed without page reloads using window hash monitoring (#home, #setup-guides, #vault-resources, #grindset, #join-us, #about-us).
  • High-Contrast Aesthetics: Enforces zero gradients, zero emojis, zero em-dashes, and clean typography tokenized via CSS variables.

2. File Specifications & Component Responsibilities

2.1 index.html

Provides the semantic HTML5 layout shell:

  • <header class="site-header">: Contains project branding (UITS_Dev_Lab), desktop navigation links, theme toggle button, and mobile hamburger button.
  • <aside class="mobile-sidebar">: Mobile slide-out navigation drawer triggered at < 768px screen width.
  • <main class="container">: Host container for all 6 section viewports (.page-section).
  • <div class="modal-overlay" id="app-modal">: Accessible centralized popup modal for displaying roadmap objectives and multiline setup instructions.
  • <footer class="site-footer">: Sticky-bottom footer container.

2.2 style.css

Contains design system tokens, responsive layout rules, and component styles:

  • CSS Custom Variables (:root / [data-theme="dark"]): Defines background surfaces (--bg-body, --bg-surface), text colors (--text-main, --text-muted), borders, and accent highlights (--accent-blue, --accent-green).
  • Sticky Layout Rules: .site-header uses position: sticky; top: 0; to adapt dynamically to navigation wrapping. main uses flex: 1 and .site-footer uses margin-top: auto to prevent content overlap.
  • Multiline Instruction Formatting: .guide-instructions { white-space: pre-line; } preserves formatting for step-by-step guides.

2.3 data.json

Central JSON data store structured into four primary collections:

  1. roadmap: Interactive 4-step onboarding steps (Step Number, Title, Summary, Objective, Resources).
  2. guides: Category-tagged setup guides (ID, Title, Category, Difficulty, Prerequisites, Multiline Steps).
  3. resources: Curated developer scripts, templates, guidelines, and tools.
  4. leaderboard: Community member activity entries (Rank, Name, Username, Score, Streak Days, Target Role, Tech Stack Tags, GitHub Link).

2.4 render.js (RenderModule)

Encapsulated DOM rendering module exporting static UI generator functions:

  • renderRoadmap(container, roadmapData, onSelectStep)
  • renderGuides(container, guidesData, activeCategory, searchQuery, onSelectGuide)
  • renderResources(container, resourcesData, activeCategory, searchQuery)
  • renderLeaderboard(container, leaderboardData)
  • openModal(title, categoryTag, metaInfo, stepsContentText)
  • closeModal()

2.5 app.js

Main application controller handling lifecycle and interactivity:

  • State Management: Holds application state object (data, currentRoute, theme, guidesFilter, guidesSearch, resourcesFilter, resourcesSearch).
  • Fetch Pipeline: Asynchronously fetches data.json on DOMContentLoaded.
  • Router Logic: Listens to hashchange events and toggles .page-section.active visibility.
  • Theme Manager: Toggles root data-theme attribute between dark and light and persists preference in localStorage.setItem('uits_theme').
  • Event Listeners: Binds category filter buttons, search input handlers, mobile menu drawer triggers, and modal overlay dismissal (ESC key, backdrop click, close button).

3. Data Schemas

Leaderboard Entry Schema

{
  "id": "1",
  "name": "Tanvir Hossain",
  "username": "tanvir-dev",
  "score": 1420,
  "streakDays": 45,
  "role": "Full Stack Engineer",
  "techStack": ["React", "Node.js", "PostgreSQL", "TypeScript"],
  "githubUrl": "https://github.com/tanvir-dev"
}

Setup Guide Schema

{
  "id": "guide-cli-env",
  "title": "Universal Terminal & Shell Environment",
  "category": "CLI",
  "difficulty": "Beginner",
  "prerequisites": "Administrator access on Windows (WSL2), macOS, or Linux.",
  "steps": "Step 1: Install Zsh or Bash latest release.\nStep 2: Configure environment path variables in .zshrc."
}

4. Version History

v1.2.0 (2026-08-03)

  • Header & Footer Layout Fix: Refactored .site-header positioning from fixed to position: sticky; top: 0; to adapt dynamically to header heights when nav links wrap.
  • Footer Pinning: Added margin-top: auto and relative positioning to .site-footer to ensure it stays anchored at the bottom of the viewport without clipping page content.
  • Scroll Margin: Added scroll-margin-top to .page-section targets for hash navigation offset.

v1.1.0 (2026-08-03)

  • Grindset Activity Leaderboard: Introduced the #grindset section to showcase community rankings based on GitHub activity, commit streaks, target engineering roles, and tech stacks.
  • Render Engine Expansion: Extended render.js with renderLeaderboard() and updated app.js state management and navigation hooks.
  • Data Integration: Added "leaderboard" dataset array to data.json.

v1.0.0 (2026-08-03)

  • Initial SPA Release: Launched core Single Page Application architecture.
  • Sections Built: #home, #setup-guides, #vault-resources, #join-us, #about-us.
  • Dynamic Content: Integrated async fetch('data.json') pipeline.
  • Interactive Features: 4-step roadmap modal overlay, live keyword search, category filtering, and dark/light theme switching with localStorage persistence.