- [Jan Rueggebeg]
Architecture
Table of contents
Overview
Team Chat is a web-based real-time messaging application designed for academic environments, specifically enabling professors to manage and moderate student group discussions. The application provides a secure, transparent platform where administrators (professors) have full oversight of all communications while students can participate in organized group chats.
The system consists of two main components:
- Flask Web Application: Handles user authentication, web interface, database operations, and REST API endpoints
- Standalone WebSocket Server: Manages real-time messaging using Rust for performance
The architecture follows a traditional MVC pattern with Flask blueprints for modularity, SQLite for data persistence, and WebSocket connections for real-time communication. Authentication supports both session-based (web) and JWT-based (API) approaches.
Codemap
Core Directory Structure
app/
├── __init__.py # App factory, CORS, JWT setup
├── db.py # Database connection, queries, CLI commands
├── auth/ # Authentication blueprint
│ ├── routes.py # Login, register, JWT endpoints
│ └── templates/ # Auth-specific templates
├── main/ # Main application blueprint
│ ├── routes.py # Chat, user, group management
│ └── templates/ # Main application templates
├── api/ # REST API blueprint
│ └── routes.py # API endpoints for external access
└── templates/
└── base.html # Base template with navigation
Key Components
Flask Blueprints:
auth_bp
(/auth/*
): Handles user registration, login, logout, and JWT token managementmain_bp
(/
): Core application functionality including chat interface, user management, and group creationapi_bp
(/api/*
): REST API endpoints for external integrations
Database Layer (app/db.py
):
- Simple SQLite database with raw SQL queries (no ORM)
- Connection management with Flask’s
g
object - CLI commands for database initialization and management
Templates:
- Jinja2 templating with a base template providing consistent navigation
- Responsive design using Tailwind CSS via CDN
- Role-based UI elements (admin vs regular user views)
Cross-cutting concerns
Authentication & Authorization
The application implements a dual authentication system:
- Session-based Authentication (Web Interface):
- Uses Flask sessions with
@login_required
decorator - Stores
user_id
,username
, androle
in session - Automatic user loading via
@auth_bp.before_app_request
- Uses Flask sessions with
- JWT Authentication (API Access):
- Access tokens (1 hour expiry) and refresh tokens (30 days)
- Used by external clients and the WebSocket server
- Tokens include user identity and additional claims
Role-based Access Control:
admin
: Full system access, can manage users and groupsuser
: Standard access to assigned conversationsguest
: Limited access, temporary accounts without passwords
Real-time Messaging Architecture
Real-time messaging is handled by a separate Rust-based WebSocket server that communicates with the Flask application’s database:
Message Types:
IdMessage
: Establishes user connection to specific conversationChatMessage
: Actual chat content with metadata
Database Design Philosophy
The application uses raw SQL queries instead of an ORM (design decision):
Benefits:
- Simple, transparent queries
- No learning overhead for additional frameworks
- Direct control over database operations
- Lightweight for the application’s complexity level
Schema:
users
: User accounts with rolesconversations
: Group/chat containersconversation_members
: Many-to-many relationship with rolesmessages
: All chat messages with timestamps
Error Handling & Logging
- Comprehensive error handling in all routes with database rollbacks
- Flask logging configured for development and production
- Flash messages for user feedback in web interface
- JSON error responses for API endpoints
Security Considerations
- Password hashing using Werkzeug’s security utilities
- CSRF protection considerations (noted as acceptable risk for admin-only forms)
- Input validation and sanitization
- Role-based route protection
- Secure session management
Development & Deployment
Development Tools:
run.sh
script for easy development setup- Flask CLI commands for database management
- Automatic server restart and cleanup handling
Dependencies:
- Minimal Flask application with essential extensions
- External WebSocket server for performance
- Tailwind CSS via CDN for styling
Most of this was written by Claude