FML HUB

Developer Dashboard

In-depth engineering and operations guide

Use this dashboard for setup, architecture decisions, chapter extensions, test strategy, branch release flow, and deployment hardening.

Local setup

  1. Clone repository and enter project root.
  2. Install dependencies in root and app folders as needed.
  3. Create local env values without committing secrets.
  4. Run app dev servers and verify route-level startup.

Build and test commands

  • npm run build from root builds both apps + portal assembly.
  • cd mathf3-o && npm run dev for Form 3 local loop.
  • cd mathf4-o && npm run dev for Form 4 local loop.
  • cd mathf4-o && npm run test for tool checks where available.

Environment requirements

  • Node.js LTS runtime
  • VITE_GROQ_API_KEY configured in local/deploy environments
  • Modern browser for chart and 3D rendering support

Repository topology

Path

Role

Primary contents

fml-framework/

Reusable framework layer

Formula modules, templates, references

mathf3-o/

Form 3 app

Chapters, AI tools, learning UI

mathf4-o/

Form 4 app

Advanced chapters, visualization tooling

portal/

Unified site shell

Main pages, docs dashboards, theme system

Architecture layers

  • Formula layer: deterministic math functions and helpers.
  • Tool schema layer: structured AI-callable definitions in aiTools.js.
  • Dispatcher layer: maps tool calls to implementations in toolDispatcher.js.
  • Chapter UX layer: lesson components, forms, graphing, and feedback UI.
  • Portal layer: launch routes, docs, and deployment communication.

Core design goal: AI augmentation with deterministic solver guarantees for accuracy and auditability.

Add a chapter or tool

  1. Create or update formula functions in chapter math utilities.
  2. Add or revise tool schema entries in aiTools.js.
  3. Map schema handlers in toolDispatcher.js.
  4. Implement chapter page UI and wire execution responses.
  5. Add tests and sample prompts to validate both normal and edge-case behavior.

Testing strategy

Functional checks

  • Formula output correctness for known datasets.
  • Input validation for invalid or incomplete values.
  • AI-to-tool mapping against expected solver path.

Release checks

  • Full root build with deploy assembly.
  • Manual route checks for /3o/ and /4o/.
  • Portal docs pages render in light and dark themes.

Release flow and branch policy

  1. Feature work lands in main after review and validation.
  2. Approved deployment set is synchronized to official-deployment.
  3. Vercel production branch tracks official-deployment for controlled releases.
  4. Optional scoped branch no-deployment-files can be used for source-only sharing.

Security and key handling

  • No private keys in git-tracked files, commits, or screenshots.
  • Use provider environment variables for runtime secrets.
  • Rotate keys immediately if accidental exposure is suspected.
  • Run repository scans before release branches are pushed.

Deep operational details are documented in: docs/developer on GitHub.