Master Platform

1. Project Vision

Master Platform is a high-performance, modular, and production-grade web application platform. It is designed to host a suite of independent, highly-optimized tools (including mock-up tests, MCQ modules, typing engines, job boards, and admin interfaces) in a single unified architecture. The core vision is to build an extensible and lightning-fast portal without the overhead of heavy frontend frameworks (e.g., React, Vue, Angular) or bulky monolithic layout libraries. By prioritizing standard HTML5, CSS3, and vanilla modern JavaScript (ES2023+), the platform delivers maximum rendering speeds, absolute control over the execution context, and a near-zero initial load footprint.

2. Objectives

• Zero Framework Overhead: Maximize runtime execution speed and eliminate virtual DOM overhead by utilizing vanilla web technologies exclusively.
• Strict Module Independence: Ensure that every single tool, module, and page behaves as a decoupled unit. One tool failing must never affect another.
• Ultimate Portability: Maintain a clean, modular structure that easily deploys to modern static hosting solutions like Cloudflare Pages, backed by serverless Firebase services for auth and persistence.
• Flawless User Experience: Provide a mobile-first, highly accessible, and search-engine-optimized ecosystem matching modern professional software design standards.
• Predictable Maintainability: Enforce strict naming conventions, file organizations, and programming patterns to enable painless multi-developer collaboration.

3. Technology Stack

• Markup: HTML5 (Semantic and fully compliant)
• Styling: Custom CSS3 (CSS Variables, Flexbox, CSS Grid)
• Scripting: Vanilla JavaScript (ES2023 modules, async/await, custom events)
• Version Control: GitHub (Git)
• Hosting & CI/CD: Cloudflare Pages & GitHub Actions
• Backend & Security: Firebase Authentication & Cloud Firestore

---

4. Folder Architecture

The project follows a modular, decoupled flat-directory system where each functional block is self-contained:

/
├── assets/             # Global static media, custom vector icons, shared images
├── config/             # Environment, feature flags, and global configuration scripts
├── auth/               # Firebase authentication interfaces, login, signup, recovery
├── jobs/               # Job portal module, listings, and applications
├── mcq/                # Multiple Choice Question tool engine
├── typing/             # Speed typing test and interactive analytics tool
├── model-test/         # Academic mock test and simulation module
├── tools/              # General standalone utilities (calculators, planners, converter tool)
├── admin/              # Restricted administration dashboard and user management portal
├── api/                # Client-side API wrappers, fetch helpers, and serverless interfaces
├── firebase/           # Global Firebase SDK initializer, schema configurations, rules
├── data/               # Static dataset stores, local storage schemas, dictionaries
├── scripts/            # Shared service workers, global helpers, third-party libraries
├── docs/               # System documentation, user guides, API definitions
├── index.html          # Global entry landing page
└── README.md           # Master Platform technical foundation documentation

---

5. Coding Standards

• Declarative and Intentional: Write self-documenting code. Prefer descriptive variable names over short cryptics.
• Single Responsibility Principle (SRP): Functions must do one thing and do it exceptionally well. Limit function length to 30 lines.
• No Inline Code: Inline <script> and <style> tags are strictly forbidden in production HTML.
• Defensive Programming: Always validate function arguments, handle exceptions gracefully with try...catch, and provide informative, user-friendly fallback behaviors.
• Immutable State: Prefer const over let. Avoid var entirely. Use Object.freeze() for static lookup maps.

6. Naming Conventions

• JavaScript Variables & Functions: Use camelCase (e.g., calculateTypingSpeed, userAuthToken).
• JavaScript Classes: Use PascalCase (e.g., FirebaseSessionManager, MockTestEngine).
• CSS Custom Properties (Variables): Use lowercase kebab-case (e.g., --color-primary, --font-scale-base).
• CSS Classes: Use standard BEM (Block-Element-Modifier) syntax in lowercase kebab-case (e.g., .card, .card__title, .card__button--disabled).
• HTML IDs: Use lowercase camelCase or kebab-case (e.g., typingInput, results-container). Be consistent per module.

7. File Naming Rules

• All HTML, CSS, and JS file names must be lower-case.
• Words in file names must be separated by hyphens (kebab-case) (e.g., typing-test.js, main-styles.css).
• Avoid abbreviations in file names. Use descriptive words (e.g., multiple-choice-question.js instead of mcq-test.js).
• Asset files (images, audio) must follow the same lowercase-hyphen rule (e.g., victory-chime.wav, hero-background.webp).

---

8. JavaScript Module Rules

• Strict ESM Mode: All JS scripts must use standard ES2023 module syntax (import/export).
• Zero Side-Effects on Import: Modules must only export functions, classes, or constants. They must not perform immediate operations or modify global state simply by being imported.
• Explicit Imports: Do not rely on global window variables. If a utility or module is required, import it explicitly.
• Encapsulation: Keep module state local. Use closures or private class fields (#privateField) to prevent accidental state mutation from external scripts.

9. CSS Organization Rules

• Decoupled Tool Styling: Each HTML page must load its own dedicated, isolated stylesheet. Sharing stylesheets between different tools is forbidden, except for a core CSS file defining root variables and layout foundations.
• Variable Driven: All layout metrics (padding, gaps), fonts, and colors must be mapped to CSS Custom Properties.
• Layouts First: Rely strictly on standard CSS Grid and Flexbox layouts. Absolute positioning must be used sparingly.
• No CSS Frameworks: Bootstrap, Tailwind, and custom styling preprocessors are prohibited in the production Vanilla build. Hand-crafted CSS ensures minimal bundle size, instant rendering, and absolute control.

10. HTML Standards

• Strict Semantic Elements: Use <main>, <header>, <footer>, <section>, <article>, <nav>, <aside> correctly. Never use nested <div> wrappers when semantic tags exist.
• Valid and Compliant: Validate all markup against modern HTML5 standards. All tag attributes must be double-quoted.
• Asset Loading Optimization: Use <link rel="preload"> for critical display assets. Use loading="lazy" on all off-screen images.
• Script Placement: Include scripts at the end of the <body> tag or use the defer / async attributes in the <head>.

---

11. Accessibility Rules (A11y)

• WCAG 2.1 AA Compliant: Text elements must have a contrast ratio of at least 4.5:1 against their background.
• Keyboard Navigable: Ensure every interactive component (buttons, inputs, links) can be fully operated via Tab, Space, and Enter keys. Always maintain visible :focus outlines.
• ARIA Attributes: Use aria-expanded, aria-live, aria-label, and role attributes appropriately when building complex dynamic controls.
• Accessible Forms: Every input must be programmatically associated with a <label> element using the for attribute.

12. SEO Rules

• Unique Metadata: Every page must have a unique, highly targeted <title> (under 60 characters) and <meta name="description"> (under 160 characters).
• Rich Snippets / Open Graph: Include standard Open Graph (og:title, og:description, og:image, og:url) and Twitter card tags on entry points.
• Structured Data: Implement JSON-LD schemas inside scripts to declare breadcrumbs, articles, or tools to search engine crawlers.
• Heading Hierarchy: Ensure exactly one <h1> element exists per page, with subsequent headers falling into a logical nested hierarchy (<h2> to <h6>).

13. Performance Rules

• Instant Start (Time to Interactive < 1.0s): Target a Google Lighthouse score of 95+ across all performance diagnostics.
• Budget-conscious: Keep the initial HTML, critical CSS, and entry JS footprint under 100KB combined.
• Caching Strategy: Service workers must aggressively cache immutable shell assets (fonts, icons, structural layouts) to support seamless offline interactions.
• Zero Reflows: Ensure all layout shifts are avoided by pre-defining width and height dimensions on image tags and media templates.

14. Security Rules

• Strict Content Security Policy (CSP): Prevent inline execution, untrusted cross-domain scripting, and unauthorized form actions.
• Data Sanitization: Never pass raw inputs into innerHTML. Use textContent or robust DOM sanitization utilities when rendering dynamic records.
• Firebase Security Rules: Configure Firestore rules to restrict access to authenticated owners exclusively. Write declarative schema validators directly within firestore.rules.
• Zero Secrets in Client Code: Protect API keys and third-party configuration parameters securely using build-time replacements or serverless proxy workers.

---

15. Git Workflow

• Branch Strategy:
  • main : Production-ready branch. Only accepts merges via pull requests from staging or audited hotfix/* branches.
  • staging : Integration branch for upcoming releases. Fully tested and validated.
  • feature/* : Development branches dedicated to single, modular additions. Created off of staging.
• Commit Messages: Follow the Conventional Commits specification:
  • feat(typing): add speed analytics chart dashboard
  • fix(auth): correct email validation regex parameter
  • docs(readme): expand deployment integration steps

16. Versioning Strategy

The project conforms strictly to Semantic Versioning 2.0.0 (SemVer):

• MAJOR (x.0.0): Introducing incompatible API changes or database schema rewrites.
• MINOR (0.x.0): Adding new functional modules, tools, or major standalone utilities in a backward-compatible manner.
• PATCH (0.0.x): Applying backward-compatible security hotfixes, layout optimizations, and minor logic updates.

---

17. Development Phases

1. Phase 1: Foundation Setup: Establish global layout standards, common reset stylesheets, authentication interfaces, and global configuration scripts.
2. Phase 2: Individual Module Integration: Build and connect standalone modules (e.g., typing, mcq, model-test) iteratively. Each undergoes rigorous local testing.
3. Phase 4: Administrative Dashboard & Analytics: Develop the /admin workspace and implement reporting pipelines connected to Firestore.
4. Phase 5: Optimization & Launch: Execute full auditing for accessibility, core web vitals, and service-worker capabilities prior to public domain deployment.

18. Module Dependency Rules

• No Circular Dependencies: A module may import from helpers, but helpers must never import from active application screens.
• Unidirectional Flow: Communication between separate sub-directories (e.g. jobs and mcq) is forbidden. If shareable state exists, it must be delegated to standard global storage managers housed within the core platform directories.

19. Deployment Workflow

[Local Development] 
       │
       ▼
[GitHub Repository] (feature/staging branches)
       │
       ▼ (Pull Request Merged)
[GitHub Actions CI/CD Pipeline]
       ├── Lint & Schema Validation Checks
       ├── Semantic Asset Optimization & Compression
       └── Run Automated Compliance/Security Audits
               │
               ▼ (Successful Build)
[Cloudflare Pages Edge Network] (Live Production Release)

20. Future Scalability Guidelines

• Containerized Extensions: When a tool requires dynamic, heavy processing, it must be developed as a separate backend API endpoint, leaving the platform edge fast and light.
• Local-First Design: Build tools to leverage client-side IndexDB schemas, transitioning seamlessly to Firestore sync layers when connectivity is restored.
• Extensible Tool Registry: Ensure new applications can register themselves within the platform layout simply by appending a configuration entry inside the config/ registries.