Overview
The Maths Society Platform uses Flask Blueprints to organize routes into logical, modular components. This architecture provides:- Separation of Concerns: Each blueprint handles a specific domain
- Maintainability: Isolated route definitions and templates
- Scalability: Easy to add new modules without affecting existing code
- Testability: Blueprints can be tested independently
Blueprint Registration
Blueprints are registered in the application factory (app/__init__.py:211):
Blueprint Structure
Main Blueprint
URL Prefix:/ (root)
Purpose: Public-facing routes including challenges, leaderboards, and content.
Location: app/main/
Routes
Homepage & Information
Homepage: Main landing page with platform overviewTemplate:
main/index.htmlAlternative homepage routeRedirects to
/ for consistencyAbout page: Platform information and mission
Privacy Policy: GDPR compliance and data handling
Challenges
Challenge list: Browse all available challengesFilters:
- By key stage (KS3, KS4, KS5)
- By release date
- By lock status
Challenge detail pageGET: Display challenge content and answer boxesPOST: Submit answers for validationAuthentication: RequiredExample:
Summer/Autumn Challenges
Autumn competition information
Autumn challenge detail (similar to regular challenges)
Content & Articles
Article list: Browse educational articlesQuery Parameters:
type: Filter by article type (“article” or “newsletter”)
Article detail: Display full article content
Newsletter archive: List all newsletters
Newsletter detail: Display/download newsletter PDF
Newsletter file serving: Secure file downloadSecurity: Validates file path to prevent directory traversal
Leaderboards
Main leaderboard: Rankings by key stageQuery Parameters:
key_stage: Filter by KS3, KS4, or KS5
Autumn competition leaderboard
Auth Blueprint
URL Prefix:/ (root)
Purpose: User authentication and registration.
Location: app/auth/
Routes
User loginGET: Display login formPOST: Authenticate user credentialsForm Fields:
email(required)password(required)remember_me(optional boolean)
User registrationPOST Fields:
full_nameemail(unique)passwordconfirm_passwordyearkey_stagemaths_class
- Email uniqueness check
- Password strength requirements
- Key stage validation (KS3, KS4, KS5)
User logoutClears session and redirects to homepage
Autumn competition registrationSimilar to
/register but sets is_competition_participant=TrueAutumn competition login
Admin Blueprint
URL Prefix:/ (root, routes start with /admin)
Purpose: Administrative functions for content and user management.
Location: app/admin/
Authentication: All routes require @login_required and admin check
Routes
Dashboard
Admin dashboard: Overview of platform statisticsDisplays:
- Total users, challenges, submissions
- Recent activity
- System health metrics
Challenge Management
Challenge list: All challenges with management actions
Create new challengeForm Fields:
titlecontent(CKEditor)key_stagerelease_at(datetime)lock_after_hoursfile_url(optional PDF)- Answer boxes (dynamic)
Edit existing challenge
Delete challengeSecurity: Confirmation required, cascades to answer boxes
Toggle manual lock
Article Management
Article list: All articles and newsletters
Create article/newsletterFields:
titlecontent(CKEditor for articles)type(“article” or “newsletter”)file_url(PDF for newsletters)named_creator(optional attribution)
Edit article
Delete article
User Management
User list: Paginated user directoryFeatures:
- Search by name/email
- Filter by key stage
- Bulk actions
User search APIQuery Parameters:
q: Search querykey_stage: Filter
User statisticsResponse:
Create user account
Edit user accountFields:
is_admin(promote/demote)key_stageschool_id
Bulk user operationsActions:
- Delete multiple users
- Change key stage
- Export to CSV
File Management
File upload handlerAccepts: PDF, imagesSecurity: File type validation, sanitized filenames
Serve challenge files
Tools
Math Engine Testing ToolInteractive interface to test mathematical expression equivalence:Features:
- Test two expressions for equivalence
- View normalized forms
- LaTeX input support
- Debugging output
Profile Blueprint
URL Prefix:/profile
Purpose: User account management and settings.
Location: app/profile/
Authentication: All routes require @login_required
Routes
User profile pageDisplays:
- User information
- Submission history
- Personal statistics
- Account settings link
Change passwordPOST Fields:
current_password(verification)new_passwordconfirm_password
Account deletionSecurity:
- Requires password confirmation
- Cascades to submissions (via model relationships)
- Irreversible action with warning
Math API Blueprint
URL Prefix:/api/math
Purpose: RESTful API for mathematical expression operations.
Location: app/math_api.py
Authentication: Required (admin only)
Endpoints
Test if two mathematical expressions are equivalentAuthentication: Required (admin only)Request Body:Response:
Normalize expression to canonical formAuthentication: Required (admin only)Request Body:Response:
URL Patterns
Naming Conventions
| Pattern | Example | Purpose |
|---|---|---|
/<resource> | /challenges | List view |
/<resource>/<int:id> | /challenge/42 | Detail view |
/<resource>/create | /admin/articles/create | Create form |
/<resource>/edit/<int:id> | /admin/challenges/edit/5 | Edit form |
/<resource>/delete/<int:id> | /admin/users/delete/10 | Delete action |
/api/<resource>/<action> | /api/math/test-equivalence | API endpoint |
URL Generation
Useurl_for() for all internal links:
Decorators & Middleware
Authentication Decorators
Admin-Only Decorator
Rate Limiting
Error Handling
Blueprint-Level Error Handlers
Global Error Handlers
Defined inapp/__init__.py:74-85
Template Organization
Each blueprint has its own template directory:Testing Blueprints
Unit Testing Routes
Related Documentation
System Architecture
Application structure overview
Database Models
Model definitions used in routes
API Reference
Complete API endpoint documentation
Authentication
User authentication implementation