🎓 Verdant Heights Academy

A prestigious, state-of-the-art secondary school web application featuring an interactive client dashboard, Tuition & Scholarship Calculator, and fully integrated student, parent, and teacher portals.

Developed with a modular React (Vite) client and a high-performance Python FastAPI backend.

---

🏛️ Project Showcase & Key Features

• Premium Glassmorphic Design: central CSS design token system implementing a custom dark mode transition toggle using clean HSL color theory.
• Tuition & Scholarship Calculator: A real-time reactive calculator tracking Day vs. Boarding status, selective enrichment academy tracks (Coding, Sports, Music), and dynamic sliding scholarship percentages.
• Persistent Admissions Inquiry: Multi-stage application wizard backed by localStorage form drafts to protect against accidental reloads or page closure.
• Interactive Roles Portal:
  • Student (Alex Mercer): Real-time homework toggle checklist.
  • Parent Portal: Live tuition invoices with an interactive "Pay Invoice" button syncing state instantly.
  • Teacher Console: Interface to record and add course grades in real time, updating the global database instantly.
• Fail-Safe Synchronization: Dynamic fallback that automatically caches form submissions locally if the backend server is offline, and syncs to the FastAPI backend once it boots up.

---

🛠️ Architecture & Tech Stack

This project is built as a decoupled Single Page Application (SPA) to ensure absolute speed, security, and separation of concerns.

       +-------------------------------------------------------+
       |                   REACT CLIENT (SPA)                  |
       |  - Renders UI Components (Navbar, Cards, Portals)     |
       |  - Tracks App State & Mock Student/Parent Database    |
       |  - Manages Local Storage Drafts                       |
       +---------------------------+---------------------------+
                                   |
                          JSON HTTP / HTTPS
                  (POST Inquiries / GET Server status)
                                   |
                                   v
       +-------------------------------------------------------+
       |                PYTHON FASTAPI BACKEND                 |
       |  - Enables CORS middleware to accept React requests   |
       |  - Schema Validation via Pydantic                     |
       |  - Simple JSON Flat-file Database (inquiries.json)    |
       +-------------------------------------------------------+

Tech Stack Details:

• Frontend: React (Vite), ES6 Module scripts, Lucide React Icons.
• Styling: Pure custom Vanilla CSS variables with responsive layouts and backdrop blur filters.
• Backend: Python 3, FastAPI, Uvicorn (ASGI web server), and Pydantic (data validation models).

---

🚀 Quick Start Guide

Method A: One-Click VS Code Integration (Recommended)

Since the workspace is fully optimized for Visual Studio Code, you can spin up the application in seconds using pre-configured workspace tasks:

1. Open the Secondary school website folder in VS Code.
2. Press Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows) to open the Command Palette.
3. Type Tasks: Run Task and press Enter.
4. Select 2. Run React Web Client to start the frontend server on http://localhost:5173.
5. (Optional) Open tasks again and select 1. Run Python API Backend to run the backend on http://127.0.0.1:8000.

---

Method B: Manual CLI Execution

If you prefer operating via the standard Terminal:

1. Start the Python Backend

From the project root:

# Install dependencies
pip install -r requirements.txt

# Run the FastAPI server
python3 server.py

The backend API will boot up on http://127.0.0.1:8000.

2. Start the React Frontend

Using the local Node binaries bundled in the workspace:

# Navigate to the client directory
cd frontend

# Run the web server using local node binaries
../node-env/bin/npm run dev

The frontend website will boot up on http://localhost:5173.

---

📚 Core Educational Concepts Implemented

This project is built to serve as an active learning resource. Key areas to study in the codebase include:

1. HSL Design Token System (frontend/src/index.css)

Rather than utility classes, styles are driven by dynamic CSS variables. We define variables inside the :root pseudo-class using the Hue, Saturation, Lightness (HSL) color space. To toggle Dark Mode, we simply swap the lightness levels on the body element, causing all children to update smoothly:

body.dark {
  --bg-main: hsl(var(--slate-hue), 47%, 6%);   /* Deep Navy */
  --text-main: hsl(var(--slate-hue), 20%, 90%); /* Soft White */
}

2. Multi-Step Form State Caching (frontend/src/pages/Admissions.jsx)

Saves form input to localStorage on every keypress. If the user accidentally navigates away, closes the tab, or loses power, their active progress is restored seamlessly when they return!

3. Starlette CORS Headers (server.py)

To allow the frontend (localhost:5173) to securely communicate with our python backend (localhost:8000), we configure Starlette's Cross-Origin Resource Sharing (CORS) middleware to prevent the browser from blocking requests.

---

📂 Project Directory Structure

├── .vscode/                     # VS Code tasks & editor automation
├── node-env/                    # Portable Node & NPM binaries for instant environment readiness
├── frontend/                    # React SPA project root
│   ├── src/
│   │   ├── components/          # Reusable UI elements (Navbar, Footer, Buttons)
│   │   ├── pages/               # Views (Home, About, Academics, Admissions, Portals)
│   │   ├── App.jsx              # Central router and dynamic gradebook/homework database
│   │   └── main.jsx             # React framework compiler entrypoint
│   ├── index.html               # Main HTML skeleton structure
│   └── package.json             # NPM package scripts & client dependencies
├── server.py                    # Python FastAPI backend server code
├── requirements.txt             # Python backend dependencies list
├── DOCUMENTATION.md             # In-depth architectural development guide
└── README.md                    # Public GitHub display file (This file!)