Part 3: Design

The back-end architecture design is detailed below.

Requirements

• Basic account management (account creation and authentication).
• Users can be assigned to a course.
• User account integration with Siyavula accounts via the API.
• Siyavula activity integration specifically practice:
  • Activity creation
  • Answer submission
  • Next question
  • Retry question

Design

Stack

• Framework: Flask
• Authentication: Flask-Login
• Data Validation: Pydantic
• ORM: SQLAlchemy
• API Communication: httpx
• Dependency Management: uv

Architecture

Database Design

Tables:

• Users

  • id
  • email: Unique, for authentication
  • name
  • surname
  • password_hash
  • grade
  • country
  • curriculum
  • siyavula_account_id: To link to Siyavula account
  • role: Either "Learner" or "Teacher".
  • created_at: Timestamp

• Courses

  • id
  • name: 'maths', 'science', 'physics' or 'chemistry'
  • created_at: Timestamp

• UserCourses

  • id:
  • user_id
  • course_id
  • assigned_at: Timestamp

Flask Blueprint Structure

• users: user authentication and account creation.
• courses: course assignments
• siyavula: Siyavula API integration

API Workflow

• Account Management:

  • /user POST and GET endpoints
    • Flask + SQLAlchemy + Flask-Login

• Course Management:

  • List Courses for User: /assignment (GET)
  • Assign Users to Courses: /assignment (POST)

• Siyavula Integration:

  • Activity Creation:
    • GET /siyavula/activity
    • Siyavula API
  • Answer Submission:
    • POST /siyavula/activity/answer
    • Siyavula API
  • Next Question:
    • GET /siyavula/activity/question
    • Siyavula API
  • Retry Question:
    • GET /siyavula/activity/retry
    • Siyavula API

Future-Proofing:

• Scalability: Use an SQL database (e.g., PostgreSQL)
• Cost-Effectiveness: Host on a minimal AWS/GCP/Fly.io instance
• Strict Pydantic models for API payloads

Example Pydantic Model:

from pydantic import BaseModel

class SiyavulaUser(BaseModel):
    external_user_id: str
    uuid: str
    role: str
    name: str
    surname: str
    grade: int
    country: str
    curriculum: str
    email: str
    dialling_code: Optional[str]
    telephone: Optional[str]
    created_at: str
    updated_at: str