Technical Documentation
Document 01 of 12

Technical Architecture Overview

Dev Team March 2026 Grio AI Education Platform

Grio AI Education Platform - Technical Architecture Overview

Document Type: Internal Technical Specification Last Updated: 2026-03-24 Status: Active Development Audience: Engineering Team

1. System Overview

Grio is built on a 6-layer architecture designed for scalability, offline resilience, and strict curriculum governance. Each layer is independent but communicates through well-defined contracts.

Architecture Layers

┌─────────────────────────────────────────────────────────┐
│                    CLIENT LAYER                         │
│  Classroom (TV+PC) | Student Web/Mobile | Teacher Portal│
└──────────────────────┬──────────────────────────────────┘
                       │ HTTPS/WebSocket
┌──────────────────────▼──────────────────────────────────┐
│                   API GATEWAY                           │
│  Auth | Rate Limit | Routing | Request Validation      │
└──────────────────────┬──────────────────────────────────┘
                       │ gRPC/REST
┌──────────────────────▼──────────────────────────────────┐
│               BACKEND SERVICES LAYER                     │
│  User | Session | Learning | Assessment | Content | Analytics
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────────┐
│            AI & CURRICULUM ENGINE LAYER                 │
│  Intent Detection | RAG | Tutoring Logic | Mode Router  │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────────┐
│                   DATA LAYER                            │
│  PostgreSQL | Qdrant | MinIO | Redis                    │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│            INTEGRATION LAYER (Future)                    │
│  Ministry Systems | UNEB | School Management            │
└─────────────────────────────────────────────────────────┘

2. Client Layer

2.1 Classroom Interface (TV + Mini PC)

Primary Use: Real-time classroom instruction via browser-based application.

UI Structure: - Top Bar (Context Lock): Displays current curriculum context: Class → Subject → Topic → Subtopic. Read-only indicator of system constraints. - Center Panel (Learning Area): Main content delivery. Mode-dependent rendering (Teach → Explore → Practice → Revision). - Avatar Position: Character positioning varies by learning mode and engagement state. - Bottom Mode Bar: Visual indicator + toggle controls for Learn/Explore/Practice/Revision modes. Teach mode locked by default.

Key Constraints: - Browser-based (Chromium, Firefox, Safari supported) - Requires persistent network connection during lessons - WebSocket for real-time teacher control (pause, advance, broadcast messages) - Touch-enabled for interactive elements

2.2 Student Interface (Web + Mobile)

Primary Use: Home learning, progress tracking, content review.

Dashboard Components: - Continue Learning: Resume interrupted lessons (session state from Classroom or home) - Subject List: Categorized by enrolled classes - Progress Tracking: Visual indicators (% complete per topic, streaks, badges) - Responsive Design: Mobile-first for offline-capable caching

2.3 Teacher Portal (Web Dashboard)

Administrative Functions: - Class management (roster, section grouping) - Content upload (curriculum override, supplementary materials) - Assignment creation and distribution - Real-time classroom control (monitor student responses during Practice Mode) - Performance analytics (class-wide progress, individual learner reports) - Session review (playback of classroom interactions for training purposes)

2.4 Admin Interface (Future Phase)

Planned for school administration and ministry-level reporting.

3. Backend Architecture

3.1 API Gateway

Responsibilities: - Authentication: JWT token validation, session management - Authorization: Role-based access control (RBAC) enforcement - Rate Limiting: Per-user, per-endpoint quotas (prevent abuse) - Routing: Service discovery, load balancing - Request Validation: Schema enforcement, sanitization - Protocol Support: REST (primary), gRPC (internal service-to-service)

Stack: Nginx or AWS API Gateway (production) → Django REST middleware (staging)

3.2 Core Microservices

Each service owns its data schema. Services communicate via REST APIs or gRPC.

User Service

Classroom Session Service

Learning Service

Assessment Service

Content Service

Analytics Service

3.3 Backend Stack

3.4 API Patterns (RESTful)

GET    /classes                          # List enrolled classes
GET    /classes/{classId}/subjects       # Subjects for a class
GET    /subjects/{subjectId}/topics      # Topics within subject
GET    /topics/{topicId}                 # Topic detail + learning objectives
GET    /lessons/{lessonId}               # Full lesson content
POST   /lessons/{lessonId}/start-teach   # Begin Teach Mode
POST   /sessions/{sessionId}/respond     # Submit student response
GET    /sessions/{sessionId}/progress    # Current session progress

4. AI Architecture (3 Layers)

4.1 Base Layer: Language Model

Phase 1 (Current): OpenAI API (GPT-4/3.5-turbo) via official SDK Phase 2+ (Future): Self-hosted LLaMA 2/Mistral 7B for cost optimization and offline capability

Selection Criteria: - Output quality (instruction-following, mathematical reasoning) - Latency (<2 seconds for classroom interactivity) - Cost efficiency at scale - Context window (minimum 4K for curriculum + chat history)

4.2 Middle Layer: RAG (Retrieval-Augmented Generation)

Architecture: - Vector Store: Qdrant (open-source, scalable vector database) - Embedding Model: OpenAI text-embedding-3-small or MiniLM (self-hosted) - Curriculum Embeddings: All curriculum content (topics, examples, definitions) pre-embedded at content publish time

RAG Flow: 1. Student query or system prompt triggers retrieval 2. Embed user input using same model as curriculum embeddings 3. Query Qdrant with top-k semantic search (k=5-10 results) 4. Return relevant curriculum context to prompt construction

Critical: RAG is MANDATORY. AI responses must never be generated without curriculum context. Enforced at prompt construction layer.

4.3 Top Layer: Grio Tutoring Engine

Custom orchestration logic that combines intent detection, mode routing, and curriculum constraints.

AI Flow (Per User Input)

Student Input (text/voice)
        ↓
Intent Detection
  ├─ Teach Mode action (e.g., "next step")
  ├─ Explore Mode query (e.g., "what is photosynthesis?")
  ├─ Practice Mode response (e.g., answer to multiple choice)
  └─ Out-of-scope (e.g., "tell me a joke")
        ↓
Mode Identification + Curriculum Context Retrieval
  ├─ Current topic/subtopic from session state
  └─ RAG query for relevant learning content
        ↓
System Prompt Construction
  ├─ Base prompt (role: age-appropriate tutor)
  ├─ Curriculum constraints (stay within topic, follow learning path)
  ├─ Mode rules (e.g., Practice Mode: only feedback, no hints)
  └─ Conversation history (last 5 exchanges)
        ↓
LLM Request (OpenAI API or self-hosted)
        ↓
Post-Processing
  ├─ Content safety scan (filter offensive/off-topic)
  ├─ Response truncation (max 150 tokens for classroom)
  └─ Format to UI (markdown → HTML, inject avatar gestures)
        ↓
UI Output → Classroom/Student Device

System Prompt Manager

Centralized, versioned system prompts for each combination of: - Age group (Primary 1-3, 4-6; Secondary 1-2, 3-4) - Curriculum (Uganda NCDC, Zambia ZEC, Kenya CBC) - Learning mode (Teach, Explore, Practice, Revision) - Subject domain (Mathematics, English, Science, etc.)

Constraints Enforced: - Topic-locking: never stray from current topic without explicit permission - Age-appropriate language and examples - Curriculum-aligned learning objectives only - Avoid hallucinations (verified facts from curriculum only)

Teaching Strategy (Grio Approach)

Each structured lesson follows: 1. Review: Recap prerequisites (bullet points, 30 seconds) 2. Introduce: New concept explanation (plain language, one analogy) 3. Examples: 2-3 concrete examples (contextualized to student’s environment) 4. Questions: Socratic questioning to check understanding (1-2 probing questions) 5. Practice: Guided practice (worksheet-style, immediate feedback)

Modes shortcut this: Explore skips steps 1 & 5; Practice starts at step 5; Revision shows only step 1.

5. Curriculum Engine

5.1 Hierarchy

Curriculum (Uganda NCDC, Zambia ZEC, Kenya CBC, etc.)
  └─ Class (Primary 1, Secondary 2, etc.)
      └─ Subject (Mathematics, English, Science)
          └─ Topic (Fractions, Photosynthesis)
              └─ Subtopic (Equivalent Fractions, Plant Adaptation)
                  └─ Lesson (Understanding Equivalent Fractions)
                      └─ LessonContent
                          ├─ Text blocks
                          ├─ Examples (AI-generated or static)
                          ├─ Practice questions
                          ├─ Video references (future)
                          └─ Learning objectives

5.2 Multi-Curriculum Support

Each curriculum version is independently versioned. Schema supports curriculum overrides by teachers.

5.3 Content Types

5.4 Learning Objectives Mapping

Every lesson, topic, and question maps to one or more learning objectives from the national curriculum. This ensures: - Student progress tracks mastery of official objectives - Teacher reports align with ministry expectations - Assessment rubrics are standardized

6. Learning Modes System

6.1 Teach Mode

Default for Classroom

6.2 Explore Mode

Student-driven Q&A

6.3 Practice Mode

Assessment-focused

6.4 Revision Mode

Rapid recall

6.5 Exam Prep Mode (Planned)

7. Data Architecture

7.1 PostgreSQL (Primary Relational DB)

Tables (Core): - users (id, email, role, school_id, created_at) - schools (id, name, region, subscription_tier) - classes (id, school_id, name, grade, teacher_id) - student_enrollments (student_id, class_id, enrollment_date) - curriculums (id, country_code, version, status) - curriculum_structure (id, curriculum_id, class_id, subject_id, topic_id, subtopic_id, lesson_id) - lessons (id, content, learning_objectives, metadata_json) - student_progress (student_id, lesson_id, status, score, last_accessed) - classroom_sessions (id, class_id, lesson_id, mode, start_time, end_time, interactions_count) - session_interactions (id, session_id, student_id, input, ai_response, timestamp)

Multi-Tenancy: Row-Level Security (PostgreSQL) enforces school isolation.

7.2 Qdrant (Vector Database)

Purpose: Semantic search for curriculum content during RAG

Collections: - curriculum_embeddings (one document per curriculum lesson + example) - Metadata: curriculum_id, class_id, topic_id, content_type, version

Operations: - Batch upsert on curriculum content changes - Similarity search (cosine) on student queries - TTL policies for old/deprecated content versions

7.3 MinIO (S3-Compatible Object Storage)

Use Cases: - Lesson media (images, PDFs, videos) - Student work samples (scanned worksheets) - Session transcripts/recordings (future)

Buckets: - curriculum-assets (immutable, versioned) - student-uploads (private per student) - session-media (classroom recordings)

7.4 Redis (Caching Layer)

Use Cases: - Session state caching (reduces PostgreSQL queries during rapid interactions) - Rate limit counters (API Gateway) - Temporary curriculum context (current lesson, topic, student progress snapshot) - Task queue (Celery)

TTL: 1 hour for session data, 24 hours for curriculum snapshots

8. Integration Layer (Future Phase)

Planned integrations with external systems:

Design Principle: Integrations are decoupled via adapters. Core platform functions independently.

9. Cross-Cutting Concerns

9.1 Authentication & Authorization

Authentication: - JWT tokens (issued by User Service upon login) - Token refresh: 15-minute access token, 7-day refresh token - OAuth 2.0 support (optional, for SSO with school systems)

Authorization (RBAC): - Super Admin: Full platform access (Grio staff) - School Admin: School-level user management, curriculum overrides, analytics - Teacher: Class management, lesson delivery control, student progress view - Student: Access own progress, enroll in classes, Explore/Practice modes - Independent Learner: Trial/freemium (limited class enrollments)

Enforcement: API Gateway validates token + route → role mapping on every request.

9.2 Multi-Tenancy

Model: Row-Level Security (RLS) in PostgreSQL

Application Level: - API Gateway injects school_id from JWT into request context - All queries automatically filtered by school

9.3 Grio Continuity (Session State Persistence)

Students can switch between Classroom → Home → Holidays without losing progress:

  1. Classroom Session: Stored in classroom-session service + Redis
  2. Student Home Session: Mirrors classroom progress (via API call at lesson end)
  3. Session Resume: Student selects “Continue Learning” → fetches last incomplete lesson
  4. Offline Syncing (Future): Mobile app caches session state; syncs when online

Mechanism: - Session state object: { lesson_id, subtopic_id, step_in_lesson, mode, last_response_time } - Updated in real-time to PostgreSQL (async via Celery task) - Upon lesson completion, session closes; student can resume next lesson

10. Critical Engineering Rules

Rule 1: AI Must NEVER Run Without Curriculum Context (RAG Enforced)

Implementation: - Every AI request requires curriculum_context_id parameter (enforced at API Gateway) - Prompt construction layer queries Qdrant before calling LLM - If RAG returns no results, return fallback response (e.g., “I’m not sure. Let’s review the lesson together.”) instead of asking LLM to improvise - Logging/monitoring alerts if RAG query returns zero results (content gap detected)

Rule 2: All Services Must Be Containerized

Rule 3: System Must Support Offline Extension (Design Now)

Current platform is online-only, but architecture permits future offline mode:

Rule 4: AI Logic, Curriculum Engine, Application Logic Must Be Separate Services

Rule 5: Classroom Always Starts in Teach Mode, Never Chat

Deployment Architecture (Reference)

Local Development:

docker-compose up -d  # Starts all services, DBs, caches

Staging (AWS/GCP): - ECS/GKE for container orchestration - RDS for PostgreSQL, Elasticache for Redis - S3 for media (MinIO mock locally)

Production (Future): - Kubernetes cluster (self-managed or managed service) - CDN for static assets (teacher portal, videos) - Monitoring: Prometheus + Grafana, ELK stack for logs

Glossary

End of Document

Last reviewed: 2026-03-24 Next review: 2026-06-24 (or upon major architecture change)

Grio AI — Project Documentation — March 2026
Database Schema & Data Model →