💻 System Architecture

Overview

HLMS (Homeschool Learning Management System) is a hybrid application using browser-based localStorage for the main student/teacher workflow and PostgreSQL for curriculum data.

┌─────────────────────────────────────────────────────────────────┐
│                    SYSTEM ARCHITECTURE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  FRONTEND (Browser)                                              │
│  ├── student-dashboard.html      ← localStorage (v1.0.1)        │
│  ├── student-assignments.html    ← localStorage (v1.0.1)        │
│  ├── teacher-review.html         ← localStorage (v1.0.1)        │
│  └── curriculum-calendar.html    ← PostgreSQL via API           │
│                                                                  │
│  BACKEND (Node.js)                                               │
│  └── server.js (port 3000)                                      │
│      ├── /api/health                                            │
│      ├── /api/weeks                                             │
│      ├── /api/weeks/:id/assignments                             │
│      ├── /api/subjects                                          │
│      └── /api/assignments/today                                 │
│                                                                  │
│  DATABASE (PostgreSQL 17)                                        │
│  └── andrews_family_lms                                         │
│      ├── school_weeks (24 rows)                                 │
│      ├── assignments (897 rows)                                 │
│      ├── subjects (9 rows)                                      │
│      └── resources (16 rows)                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Technology Stack

File Structure

E:\Lucas\Personal-Productivity\
├── server.js                     # Express API server
├── package.json                  # Node.js config
├── .env.local                    # Environment variables
│
├── dashboards/                   # Frontend HTML files
│   ├── student-dashboard.html    # Student home page
│   ├── student-assignments-enhanced.html  # Assignment work
│   ├── teacher-review.html       # Teacher grading portal
│   ├── submission-review.html    # PDF-style view
│   ├── curriculum-calendar.html  # Week/day assignment view
│   ├── homeschool-login.html     # Role selection
│   └── homeschool-settings.html  # PIN configuration
│
├── docs/                         # Documentation (this site)
│   ├── index.html
│   ├── glossary.html
│   ├── student/
│   ├── teacher/
│   ├── developer/
│   ├── reference/
│   └── assets/
│
├── database/                     # SQL scripts
│   ├── schema.sql
│   ├── seed-weeks.sql
│   └── seed-assignments.sql
│
└── .claude/                      # Claude configuration
    └── agents/
        ├── testing-agent-v2.md
        ├── confidence-scoring.md
        ├── regression-risk-scoring.md
        └── project-suites.md

Data Flow

Student Submission Flow

Student Types Work
       │
       ▼
Auto-Save (5s) → localStorage['assignmentDrafts']
       │
       ▼
Click Submit
       │
       ▼
Save to localStorage['studentSubmissions']
       │
       ▼
Create teacherNotification
       │
       ▼
Mark Assignment Complete
       │
       ▼
Teacher Sees in Pending Tab

Teacher Grading Flow

Teacher Opens Submission
       │
       ├── Review Content
       ├── View Reflections
       └── View Canvas/Photos
              │
              ▼
       ┌──────┴──────┐
       │             │
Return for      Give Final
Revision          Grade
       │             │
       ▼             ▼
status='returned'  status='graded'
grade=null         grade='A'
       │             │
       └──────┬──────┘
              │
              ▼
Create studentNotification
              │
              ▼
Student Sees Feedback

Key Components

Quill.js Editor

Rich text editing for Writing, Reading, Science, and Spelling assignments.

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      ['bold', 'italic', 'underline'],
      [{ 'list': 'ordered'}, { 'list': 'bullet' }]
    ]
  }
});

Canvas Drawing

HTML5 Canvas for Math assignments with draw/erase modes and color selection.

// Core drawing function
function draw(e) {
  if (!isDrawing) return;
  const rect = canvas.getBoundingClientRect();
  const x = e.clientX - rect.left;
  const y = e.clientY - rect.top;
  
  ctx.strokeStyle = currentColor;
  ctx.lineWidth = 2;
  ctx.lineTo(x, y);
  ctx.stroke();
}

Notification System

Bidirectional notifications between student and teacher.

// Student notification keys
localStorage['userNotifications']

// Teacher notification keys  
localStorage['teacherNotifications']

// Notification structure
{
  id: 'notif_' + Date.now(),
  timestamp: new Date().toISOString(),
  read: false,
  title: '📝 Assignment Returned',
  message: 'Your Math assignment has been reviewed.',
  action: {
    type: 'viewAssignment',
    assignmentId: 'math'
  }
}

Database Schema

PostgreSQL stores curriculum data (not student work - that's in localStorage).

-- Core tables
school_weeks    (24 rows)  - Week metadata and goals
subjects        (9 rows)   - Subject definitions with colors
resources       (16 rows)  - Curriculum resources
assignments     (897 rows) - Daily assignments

-- Key relationships
assignments.week_id → school_weeks.id
assignments.subject_id → subjects.id
assignments.resource_id → resources.id

Connection

// Node.js connection
const { Pool } = require('pg');
const pool = new Pool({
  host: 'localhost',
  port: 5432,
  database: 'andrews_family_lms',
  user: 'postgres',
  password: '[configured in .env.local]'
});

Running Locally

Start the Server

cd E:\Lucas\Personal-Productivity
npm start
# Server runs on http://localhost:3000

Access Points

• API Health: http://localhost:3000/api/health
• Student Dashboard: Open dashboards/student-dashboard.html directly
• Teacher Portal: Open dashboards/homeschool-login.html → Teacher
• Curriculum Calendar: Requires server running

Troubleshooting

# If port conflict
taskkill /F /IM node.exe   # Kill all Node processes
npm start                   # Restart fresh