TiQer Standalone - System Architecture

Last Updated: December 31, 2024 Version: 1.0

---

Overview

TiQer Standalone is a multi-platform educational quiz system consisting of:

• Web Application (React/Next.js) - Teacher/Admin interface for setup and session control
• Mobile Application (React Native) - Student interface for ArUco scanning and quiz participation
• Backend API (Django REST) - Central data management and business logic
• Firebase Realtime Database - Real-time synchronization for Mirror Mode
• PostgreSQL - Primary data storage
• Redis - Caching and message broker

---

High-Level Architecture Diagram

📊 Diagram: High-Level System Architecture | Open in Mermaid Editor

📝 View Mermaid Code (click to expand)

graph TB
    subgraph "Client Layer"
        WebApp["Web Application<br/>(React/Next.js)<br/>Teacher Interface"]
        MobileApp["Mobile Application<br/>(React Native)<br/>Student Interface"]
    end

    subgraph "API Gateway"
        NGINX["NGINX<br/>Reverse Proxy"]
        DRF["Django REST Framework<br/>API Endpoints"]
        JWT["JWT Authentication"]
        CORS["CORS Middleware"]
    end

    subgraph "Application Layer"
        Auth["Authentication App<br/>User, Roles, Permissions"]
        Org["Organizations App<br/>Multi-tenancy"]
        Classes["Classes App<br/>Class, Participants"]
        Quizzes["Quizzes App<br/>Quiz, Questions, Options"]
        Sessions["Sessions App<br/>TiQerSession, DeviceSync<br/>ArUcoCard, SessionState"]
        Responses["Responses App<br/>TiQerResponse, TiQerAnswer"]
        Analytics["Analytics App<br/>Performance Tracking"]
    end

    subgraph "Integration Layer"
        Firebase["Firebase Realtime DB<br/>Mirror Mode Sync"]
        FCM["Firebase Cloud Messaging<br/>Push Notifications"]
        S3["AWS S3<br/>Media Storage"]
        OAuth["Google OAuth<br/>SSO Authentication"]
    end

    subgraph "Data Layer"
        PostgreSQL["PostgreSQL<br/>Primary Database<br/>Schema: tiqer_standalone"]
        Redis["Redis<br/>Cache + Celery Broker"]
    end

    subgraph "Background Jobs"
        Celery["Celery Workers<br/>Async Tasks"]
        CeleryBeat["Celery Beat<br/>Scheduled Tasks"]
    end

    WebApp -->|HTTPS/REST API| NGINX
    MobileApp -->|HTTPS/REST API| NGINX
    WebApp -.->|WebSocket/Listeners| Firebase
    MobileApp -.->|WebSocket/Listeners| Firebase

    NGINX --> DRF
    DRF --> JWT
    DRF --> CORS

    JWT --> Auth
    CORS --> Auth

    Auth --> Org
    Auth --> Classes
    Org --> Classes
    Org --> Quizzes
    Classes --> Sessions
    Quizzes --> Sessions
    Sessions --> Responses
    Responses --> Analytics

    Auth --> PostgreSQL
    Org --> PostgreSQL
    Classes --> PostgreSQL
    Quizzes --> PostgreSQL
    Sessions --> PostgreSQL
    Responses --> PostgreSQL
    Analytics --> PostgreSQL

    Sessions -.->|Sync State| Firebase
    Sessions -.->|Push| FCM
    Quizzes --> S3
    Auth --> OAuth

    DRF --> Redis
    Celery --> Redis
    CeleryBeat --> Celery
    Celery --> PostgreSQL
    Celery --> Firebase

Loading

---

Layered Architecture

1. Client Layer

Web Application (Teacher/Admin Interface)

• Technology: React/Next.js
• Purpose: Data setup, session control, analytics
• Key Features:
  • Organization, Class, Student management
  • Quiz creation with WYSIWYG editor (CKEditor)
  • Session control panel (Start/Pause/Resume/End)
  • Live analytics dashboard
  • Mirror Mode display (shows same state as student devices)
  • My Library (quiz templates, search, clone)

Mobile Application (Student Interface)

• Technology: React Native (iOS + Android)
• Purpose: Session participation, ArUco scanning
• Key Features:
  • Student login (username/password + Google OAuth)
  • Session join via code or QR scan
  • ArUco card scanner (Camera-based marker detection)
  • Answer submission
  • Mirror Mode display (synchronized with teacher)
  • Session history

---

2. API Gateway Layer

• NGINX: Reverse proxy, SSL termination, load balancing
• Django REST Framework: RESTful API endpoints
• JWT Authentication: Token-based auth (access + refresh tokens)
• CORS Middleware: Cross-origin request handling for Web/Mobile clients

API Versioning: /api/v1/

---

3. Application Layer (Django Apps)

authentication

• User management (custom User model)
• JWT token generation and validation
• Role-based access control (RBAC)
• Login attempts tracking
• Password reset flow

organizations

• Multi-tenant organization management
• Organization member roles (Admin, Teacher, Student)
• Organization settings and configuration

classes

• Class/Classroom management
• Student enrollment (Participant model)
• Class-level permissions

quizzes

• Quiz CRUD operations
• Question and Option management
• Quiz publishing workflow
• Image upload to S3
• Quiz sharing (My Library)

sessions

• TiQer session lifecycle (Setup → Active → Paused → Ended)
• Device synchronization (TiQerDeviceSync)
• Session state management (TiQerSessionState)
• ArUco card assignment and tracking
• Conflict resolution for multi-device scenarios
• Real-time Firebase sync coordination

responses

• Student response capture (TiQerResponse)
• Answer recording (TiQerAnswer)
• ArUco scan metadata tracking
• Response validation

analytics

• Student performance analytics
• Quiz analytics (correctness, participation)
• Organization-level rollup reporting

---

4. Integration Layer

Firebase Realtime Database

• Purpose: Mirror Mode synchronization
• Data Synced:
  • Current question index
  • Session status (Active/Paused/Ended)
  • Connected devices count
  • Question content and options
• Sync Pattern: Backend → Firebase → All Clients (Web + Mobile)
• Latency: Sub-second real-time updates

Firebase Cloud Messaging (FCM)

• Push notifications to mobile devices
• Session start/end notifications
• Question navigation alerts

AWS S3

• Quiz question images
• User profile images
• Uploaded media files

Google OAuth

• Single Sign-On (SSO) for teachers and students
• OAuth 2.0 flow

---

5. Data Layer

PostgreSQL 14

• Schema: tiqer_standalone
• Purpose: Primary data storage
• Key Tables:
  • User, Organization, Class, Participant
  • Quiz, Question, Option
  • TiQerSession, TiQerDeviceSync, ArUcoCard
  • TiQerResponse, TiQerAnswer
  • Analytics aggregation tables

Redis 7

• Purpose: Cache + Celery message broker
• Usage:
  • Session data caching
  • API response caching
  • Celery task queue
  • Rate limiting

---

6. Background Jobs Layer

Celery Workers

• Asynchronous task execution
• Firebase sync operations
• Device heartbeat monitoring
• Analytics aggregation
• Email sending (future)

Celery Beat

• Scheduled tasks (cron-like)
• Stale device cleanup
• Session timeout monitoring
• Daily analytics rollup

---

Mirror Mode Architecture

Mirror Mode is the real-time synchronization mechanism where the teacher's Web interface and all student Mobile devices display identical quiz state during session execution.

How Mirror Mode Works:

📊 Diagram: Mirror Mode Synchronization Sequence | Open in Mermaid Editor

📝 View Mermaid Code (click to expand)

sequenceDiagram
    participant Teacher as Teacher (Web)
    participant Backend as Django Backend
    participant Firebase as Firebase Realtime DB
    participant Student1 as Student 1 (Mobile)
    participant Student2 as Student 2 (Mobile)

    Teacher->>Backend: Advance to Question 2
    Backend->>Backend: Update TiQerSessionState
    Backend->>Firebase: Write current_question: 2
    Firebase-->>Teacher: Broadcast state update
    Firebase-->>Student1: Broadcast state update
    Firebase-->>Student2: Broadcast state update

    Note over Teacher,Student2: All devices show Question 2 simultaneously

    Student1->>Backend: Submit Answer
    Backend->>Firebase: Update answered_count
    Firebase-->>Teacher: Update live results

Loading

Mirror Mode Components:

1. TiQerSessionState Model (Backend)

   • Tracks current_question_index
   • Stores session_status (Active/Paused)
   • Records last_update timestamp

2. Firebase Realtime Database (Sync Layer)

   • Path: /sessions/{session_token}/state
   • WebSocket listeners on all devices
   • Sub-second latency

3. Frontend Listeners (Web + Mobile)

   • React useEffect hooks with Firebase listeners
   • Auto-update UI when state changes
   • Reconnection logic for network issues

Data Synchronized in Mirror Mode:

• Current question index
• Session status (Active/Paused/Ended)
• Timer state (if timed quiz)
• Live participation count
• Answer submission status

---

Data Flow: Setup → Execution → Submission

Phase 1: Data Setup (Web → Backend)

📊 Diagram: Data Setup Flow | Open in Mermaid Editor

📝 View Mermaid Code (click to expand)

flowchart LR
    Teacher[Teacher on Web] -->|1. Create Org| Backend[Django Backend]
    Teacher -->|2. Create Classes| Backend
    Teacher -->|3. Add Students| Backend
    Teacher -->|4. Create Quiz| Backend
    Backend -->|5. Save to| PostgreSQL[(PostgreSQL)]
    Backend -->|6. Upload Images| S3[AWS S3]

Loading

Phase 2: Session Execution (Web + Mobile)

📊 Diagram: Session Execution Flow | Open in Mermaid Editor

📝 View Mermaid Code (click to expand)

flowchart TB
    Teacher[Teacher on Web] -->|1. Start Session| Backend[Django Backend]
    Backend -->|2. Create TiQerSession| PostgreSQL[(PostgreSQL)]
    Backend -->|3. Initialize State| Firebase[Firebase Realtime DB]

    Student[Student on Mobile] -->|4. Join via Code| Backend
    Backend -->|5. Create DeviceSync| PostgreSQL
    Backend -->|6. Notify Join| Firebase

    Firebase -.->|7. Sync State| Teacher
    Firebase -.->|8. Sync State| Student

Loading

Phase 3: ArUco Scanning (Mobile → Backend)

📊 Diagram: ArUco Scanning Flow | Open in Mermaid Editor

📝 View Mermaid Code (click to expand)

flowchart LR
    Student[Student on Mobile] -->|1. Scan ID Card| Camera[Camera API]
    Camera -->|2. Detect ArUco| OpenCV[OpenCV/ArUco]
    OpenCV -->|3. Send Marker ID| Backend[Django Backend]
    Backend -->|4. Validate Card| PostgreSQL[(ArUcoCard Table)]
    Backend -->|5. Allow Scanning| Student

    Student -->|6. Scan Answer Card| Camera
    Camera -->|7. Detect Answer| OpenCV
    OpenCV -->|8. Submit Answer| Backend
    Backend -->|9. Save Response| PostgreSQL
    Backend -->|10. Update Firebase| Firebase[Firebase]
    Firebase -.->|11. Live Update| Teacher[Teacher Dashboard]

Loading

---

Communication Protocols

REST API (Web/Mobile ↔ Backend)

• Protocol: HTTPS
• Format: JSON
• Auth: JWT Bearer tokens
• Endpoints: /api/v1/{resource}/

WebSocket/Firebase Listeners (Mirror Mode)

• Protocol: WebSocket (Firebase SDK)
• Purpose: Real-time state synchronization
• Data Format: JSON
• Reconnection: Automatic with exponential backoff

Celery Task Queue

• Broker: Redis
• Protocol: AMQP-like (Redis protocol)
• Serialization: JSON

---

Technology Stack Summary

Layer	Technology	Version	Purpose
Web Frontend	React/Next.js	13.x	Teacher interface
Mobile Frontend	React Native	0.72.x	Student interface
Backend Framework	Django	4.2.7	REST API
REST API	Django REST Framework	3.14.0	API endpoints
Database	PostgreSQL	14	Primary data store
Cache/Broker	Redis	7	Cache + Celery
Task Queue	Celery	5.3.4	Async tasks
Real-time Sync	Firebase Realtime DB	-	Mirror Mode
Push Notifications	Firebase Cloud Messaging	-	Mobile notifications
Media Storage	AWS S3	-	Image uploads
Authentication	JWT + Google OAuth	-	User auth
Image Processing	OpenCV	4.x	ArUco detection
Web Server	NGINX	1.24+	Reverse proxy
WSGI Server	Gunicorn	21.x	Python app server

---

Security Architecture

Authentication Flow

1. User logs in via Web/Mobile (email + password or Google OAuth)
2. Backend validates credentials
3. Backend generates JWT access token (15 min) + refresh token (7 days)
4. Client stores tokens securely (httpOnly cookie for Web, Keychain/Keystore for Mobile)
5. Client includes access token in Authorization: Bearer <token> header
6. Backend validates token on each request
7. Client refreshes access token using refresh token when expired

Authorization (RBAC)

• Roles: Admin, Teacher, Student
• Permissions: View, Create, Edit, Delete, Manage
• Scope: Organization-level and Class-level permissions
• Enforcement: Django permissions + custom decorators

Data Security

• HTTPS/TLS for all API communication
• JWT token blacklisting on logout
• Password hashing with Django's PBKDF2
• SQL injection protection via Django ORM
• XSS protection via DRF serializers
• CSRF protection for Web (not needed for JWT API)

---

Scalability Considerations

Horizontal Scaling

• Web/Mobile: Static hosting on CDN (Vercel, AWS CloudFront)
• Backend API: Multiple Gunicorn workers behind NGINX load balancer
• Celery Workers: Scale workers independently based on queue depth
• Database: Read replicas for analytics queries

Caching Strategy

• Redis caching for:
  • User sessions
  • Organization settings
  • Quiz metadata
  • API responses (short TTL)
• Cache invalidation on data updates

Performance Optimization

• Database indexing on foreign keys and lookup fields
• Pagination for list endpoints (max 100 items per page)
• Lazy loading for images
• Compression (gzip) for API responses
• Connection pooling for PostgreSQL

---

High Availability

Redundancy

• Multi-AZ deployment for PostgreSQL (AWS RDS)
• Redis cluster with replication
• Multiple backend server instances
• Firebase's built-in redundancy

Monitoring

• Health check endpoints (/health/)
• Application Performance Monitoring (APM)
• Firebase console for real-time sync monitoring
• Celery Flower for task monitoring

Backup Strategy

• PostgreSQL automated daily backups (AWS RDS)
• 7-day backup retention
• Point-in-time recovery capability
• S3 versioning for media files

---

Development vs Production Architecture

Development Environment

• Docker Compose for PostgreSQL + Redis
• Django development server (runserver)
• Local Celery worker
• Firebase development project
• Local S3 emulation (minio)

Production Environment

• AWS RDS for PostgreSQL
• AWS ElastiCache for Redis
• Gunicorn + NGINX for Django
• Celery with Supervisor
• Firebase production project
• AWS S3 for media
• AWS CloudFront CDN
• SSL/TLS certificates (Let's Encrypt)

---

Future Enhancements

• WebSocket API: Migrate from Firebase to Django Channels for full control
• GraphQL: Add GraphQL endpoint for complex queries
• Offline Mode: Mobile app offline support with sync queue
• Analytics ML: Machine learning for student performance predictions
• Video Streaming: Live session recording and playback
• Internationalization: Multi-language support (i18n)

---

Maintained by: Mohan Reddy Last Review: December 31, 2024