GradeFlow 🎓📊

Universal Academic Performance & Longitudinal Analytics Platform
Transform scattered grade reports, transcripts, and diplomas into actionable, visual academic insights — agnostic of educational tier and ingestion format.

---

🌟 Overview

Students and families accumulate report cards, university transcripts, and course certificates in fragmented formats: physical printouts, PDFs, Word documents, or scanned photos. Evaluating long-term progress across semesters, terms, or trimesters is often tedious and error-prone.

GradeFlow solves this problem by providing:

1. Universal Tier Support: From qualitative primary school evaluations (Avanzado, Muy Bueno) to high school trimesters and credit-weighted university degree transcripts.
2. Multimodal Ingestion: Ingest academic records from PDFs, Word documents (.docx), and scanned report card photos (Vision AI / OCR).
3. Incremental Timeline Updates: Add new terms period by period (e.g. 1st Trimester, Mid-term, Final) with automatic timeline merging, deduplication, and cumulative GPA recalculation.
4. Interactive Dashboard: Instant visualization of GPA trajectory, subject radar comparisons, credit progression, and teacher observations.
5. 100% Client-Side Privacy: All data can be stored locally in the browser (LocalStorage / IndexedDB) with zero external tracking, plus instant JSON and Excel export/import.

---

🤖 Agentic Architecture (Multi-Agent Engineering)

GradeFlow was architected and developed using a collaborative Multi-Agent Orchestration framework:

flowchart TD
    Lead["Lead Orchestrator (@lead-orchestrator)"]
    Backend["Backend & AI Ingestion (@backend-ai-dev)"]
    Frontend["Frontend & UX Specialist (@frontend-dev)"]
    QA["QA & Validation Engineer (@qa-tester)"]
    Docs["Technical Writer (@docs-writer)"]

    Lead --> Backend
    Lead --> Frontend
    Lead --> QA
    Lead --> Docs

    Backend -->|"JSON Contract"| Contract[("Universal Academic Schema")]
    Frontend -->|"Consumes & Visualizes"| Contract
    QA -->|"Validates Contracts & Math"| Contract
    Docs -->|"Documents Schema & Services"| Contract

Loading

• @lead-orchestrator: Overall system design, governance of the JSON schema contract, and Git workflows.
• @backend-ai-dev: Document parsing (PDF, DOCX, Images), scale normalization, and incremental merge engine.
• @frontend-dev: Responsive SPA, multimodal dropzone, Chart.js visualizations, and local persistence.
• @qa-tester: Schema integrity verification, weighted vs. unweighted GPA math tests, and synthetic benchmark datasets.
• @docs-writer: Technical documentation, schema/API specifications, user onboarding guides, and changelogs.

All agent prompt definitions and constraints reside in .agents/agents/.

---

📐 Universal Data Contract

GradeFlow enforces a flexible, standardized schema defined in schemas/academic-record.schema.json:

{
  "student": {
    "name": "Alex García",
    "institution": "Universidad Tecnológica",
    "program": "Ingeniería en Sistemas",
    "academicLevel": "university"
  },
  "gradingScheme": {
    "type": "numeric_10",
    "minPassingGrade": 4.0,
    "maxGrade": 10.0,
    "weightsCredits": true
  },
  "periods": [
    {
      "periodId": "2024-S1",
      "year": 2024,
      "periodName": "1er Semestre",
      "periodType": "semester",
      "status": "completed",
      "periodGPA": 8.75,
      "records": [
        {
          "subjectName": "Algoritmos y Estructuras de Datos",
          "area": "Ciencias de la Computación",
          "credits": 6,
          "gradeNumeric": 9.0,
          "status": "passed"
        }
      ]
    }
  ]
}

---

🚀 Quickstart & Live Preview

Running Locally

Because GradeFlow is designed as a zero-dependency, static web application:

1. Clone or download this repository:

   git clone https://github.com/your-user/gradeflow.git
   cd gradeflow

2. Open src/index.html directly in any web browser (Chrome, Edge, Firefox, Safari).
3. Toggle between pre-loaded sample datasets:
   • University: Computer Science curriculum with credit-weighted GPAs.
   • High School: Trimester-based numeric 1-10 grades with subject comparisons.
   • Primary School: Qualitative competencies and attendance tracking.

---

📁 Repository Structure

academitrack/
├── .agents/
│   └── agents/                 # Formal multi-agent definitions
│       ├── lead-orchestrator.md
│       ├── backend-ai-dev.md
│       ├── frontend-dev.md
│       └── qa-tester.md
├── data/
│   └── samples/                # Synthetic multi-tier demo datasets
│       ├── demo-university.json
│       ├── demo-secondary.json
│       └── demo-primary.json
├── schemas/
│   └── academic-record.schema.json  # Universal JSON Schema
├── services/                   # Ingestion & timeline services
│   ├── timeline_engine.py      # Merge logic & GPA calculation
│   └── document_parser.py      # Multi-format document parsing interface
├── src/                        # Standalone Web Application
│   ├── index.html              # Main interactive dashboard
│   ├── css/
│   │   └── styles.css          # Design system & responsive styles
│   └── js/
│       ├── app.js              # State manager, dropzone, and persistence
│       └── charts.js           # Modular Chart.js visualization engine
├── tests/                      # QA automated validation suite
│   └── test_schemas.py         # Schema & arithmetic tests
├── .gitignore                  # Strict privacy & build sanitization
├── LICENSE                     # MIT License
└── README.md                   # Project documentation

---

🔒 Privacy & Open Source Notice

GradeFlow adheres to Privacy-by-Design:

• No user data or student records are sent to external analytics or private trackers.
• Sample datasets in data/samples/ are 100% synthetic and anonymized.
• The repository .gitignore ensures no personal PDF or image files are committed.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.