Skip to content

DEVELOPMENT_GUIDE.md

Latest commit

 

History

History
76 lines (61 loc) · 2.54 KB

DEVELOPMENT_GUIDE.md

File metadata and controls

76 lines (61 loc) · 2.54 KB
Raw

Development Guide: EdTech Automata Pro 3.0

Welcome to the development team! This guide will help you set up the project on your local machine and explain the daily workflow for adding features and fixing bugs.

1. Local Setup

Prerequisites

  • Node.js (v18+ recommended)
  • A Firebase Project (with Auth and Firestore enabled)

Installation

  1. Clone the repository.
  2. Install dependencies: 
    npm install
  3. Copy the environment variables template: 
    cp .env.example .env
  4. Fill in the .env file with your Firebase configuration. You can find these details in your Firebase Console under Project Settings.

Running the App

To start the Vite development server:

npm run dev

The app will usually be available at http://localhost:5173/.

To build the app for production:

npm run build

2. Core Concepts for Development

A. Routing and Navigation

We do not use React Router or Vue Router. Navigation is handled by pageRouter.js.

  • The HTML for all pages is typically pre-loaded or injected.
  • pageRouter.js listens to navigation clicks, hides all sections, and shows the requested section.
  • To add a new page:
    1. Add a section ID in index.html.
    2. Add the navigation link.
    3. Register the route in pageRouter.js.

B. State Management

Never store global data in local variables inside your module. Always use state.js.

import { state } from './modules/state.js';

// Get current exam
const activeExamId = state.selectedExamId;

// Update state
state.setUserRole('admin');

C. Database Operations

Never import Firebase directly into a UI component. All data reads and writes must pass through firestoreService.js. This is strictly enforced because firestoreService.js handles our critical localforage offline caching layers.

Correct:

import { fetchStudents } from '../firestoreService.js';
const students = await fetchStudents(examId);

D. Writing UI

Because we use Vanilla JS, DOM manipulation is done manually.

  • Use document.getElementById or document.querySelector.
  • Use the shared builders in uiComponents.js when possible (e.g., createButton(), renderSkeletonLoader()).
  • Always clean up event listeners if you dynamically destroy DOM elements to prevent memory leaks.

3. Deployment

The project is configured to deploy easily to Firebase Hosting, Vercel, or Netlify. The standard production build command npm run build optimizes all assets into the dist/ folder, chunking heavy libraries appropriately.