Add Technical Handout (restrucktured)
parent
105fe30ba3
commit
c997776fc6
1 changed files with 263 additions and 0 deletions
263
Technical-Handout-%28restrucktured%29.md
Normal file
263
Technical-Handout-%28restrucktured%29.md
Normal file
|
|
@ -0,0 +1,263 @@
|
||||||
|
# Technical Handout: PGG (Peer Group Grading) API
|
||||||
|
|
||||||
|
## 1. Why Do We Want to Implement APIs?
|
||||||
|
|
||||||
|
Based on our implementation, we chose to build APIs for the following reasons:
|
||||||
|
|
||||||
|
- **Separation of Frontend and Backend**: Our API provides a clean interface between the Web UI and the Rust backend, allowing independent development and deployment
|
||||||
|
- **Security Layer**: We implemented session-based authentication with Redis session storage and password hashing using Argon2
|
||||||
|
- **Modularity**: Our controller-based architecture (`auth.rs`, `user.rs`, `project.rs`, `group.rs`) allows for clean code organization
|
||||||
|
- **Type Safety**: Using Rust with Actix-web and Sea-ORM provides compile-time guarantees and prevents common runtime errors
|
||||||
|
- **Scalability**: The stateless API design with external session storage (Redis) allows horizontal scaling
|
||||||
|
|
||||||
|
## 2. Who Is the User?
|
||||||
|
|
||||||
|
**Primary Users:**
|
||||||
|
- **Teachers**: Educational professionals managing peer group evaluations
|
||||||
|
- Need to create and manage projects
|
||||||
|
- Assign students to groups
|
||||||
|
- Track and evaluate peer assessments
|
||||||
|
|
||||||
|
**System Users:**
|
||||||
|
- **Administrators**: Can create user accounts with secure passwords
|
||||||
|
- **Students** (Future): Will be able to view their group assignments and submit peer evaluations
|
||||||
|
|
||||||
|
## 3. What User Problems Are We Solving and What Benefits Are We Creating?
|
||||||
|
|
||||||
|
### Problems Solved:
|
||||||
|
- **Manual Group Management**: Teachers currently track peer groups in spreadsheets or paper
|
||||||
|
- **Security Issues**: No secure way to store sensitive grading data and user credentials
|
||||||
|
- **Data Integrity**: Risk of data loss or corruption with manual systems
|
||||||
|
- **Access Control**: No way to restrict access to sensitive grading information
|
||||||
|
|
||||||
|
### Benefits Created:
|
||||||
|
- **Automated Workflows**: CRUD operations for projects, groups, and users
|
||||||
|
- **Secure Authentication**: Session-based auth with Redis and Argon2 password hashing
|
||||||
|
- **Data Persistence**: PostgreSQL database with migrations using Sea-ORM
|
||||||
|
- **Audit Trail**: All changes tracked through database transactions
|
||||||
|
- **RESTful Interface**: Standard HTTP methods for easy integration
|
||||||
|
|
||||||
|
## 4. What Concrete Outcomes Do We Want to Achieve?
|
||||||
|
|
||||||
|
### Implemented Features:
|
||||||
|
- ✅ **User Management**: Create, read, update, delete users with secure password storage
|
||||||
|
- ✅ **Authentication**: Login/logout with session management
|
||||||
|
- ✅ **Project Management**: Full CRUD for projects
|
||||||
|
- ✅ **Database Migrations**: Automated schema management
|
||||||
|
- ✅ **API Documentation**: OpenAPI/Swagger UI integration
|
||||||
|
- ✅ **Testing Infrastructure**: Unit and integration tests
|
||||||
|
|
||||||
|
### Technical Achievements:
|
||||||
|
- **Response Times**: Fast API responses using Actix-web
|
||||||
|
- **Security**: Argon2 for password hashing, session-based authentication
|
||||||
|
- **Database Integrity**: Foreign key constraints and transactions
|
||||||
|
- **Error Handling**: Comprehensive error types with proper HTTP status codes
|
||||||
|
|
||||||
|
## 5. How Do We Plan to Execute the API Program?
|
||||||
|
|
||||||
|
### Current Technology Stack:
|
||||||
|
```toml
|
||||||
|
# From Cargo.toml
|
||||||
|
- Language: Rust (Edition 2021)
|
||||||
|
- Web Framework: Actix-web 4
|
||||||
|
- ORM: Sea-ORM with PostgreSQL
|
||||||
|
- Session Storage: Redis with actix-session
|
||||||
|
- Authentication: Argon2 for password hashing
|
||||||
|
- API Documentation: utoipa with Swagger UI
|
||||||
|
- Testing: Built-in Rust testing with testcontainers
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deployment Strategy:
|
||||||
|
- **Static Binary**: Compiled as a statically linked Rust binary (as mentioned in original handout)
|
||||||
|
- **Docker Support**: `backend.Dockerfile` for containerized deployment
|
||||||
|
- **Environment Configuration**: `.env` file support with dotenvy
|
||||||
|
|
||||||
|
### Database Schema:
|
||||||
|
```rust
|
||||||
|
// Entities from our Sea-ORM models
|
||||||
|
- User (id, username, name)
|
||||||
|
- LocalAuth (id, hash, password_change_required)
|
||||||
|
- Project (id, name)
|
||||||
|
- Group (id, project_id, name)
|
||||||
|
- UserGroupProject (user_id, group_id, project_id) // Junction table
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. What Is the Architectural Style and Why Did We Choose It?
|
||||||
|
|
||||||
|
### REST (Representational State Transfer)
|
||||||
|
|
||||||
|
We implemented a RESTful API as evidenced by our route structure:
|
||||||
|
```rust
|
||||||
|
// From controller.rs
|
||||||
|
cfg.service(web::scope("/project").configure(project::setup))
|
||||||
|
.service(web::scope("/group").configure(group::setup))
|
||||||
|
.service(web::scope("/user").configure(user::setup))
|
||||||
|
.service(web::scope("/auth").configure(auth::setup))
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why REST?
|
||||||
|
- **Simplicity**: Standard HTTP verbs (GET, POST, PUT, DELETE) as seen in our controllers
|
||||||
|
- **Statelessness**: Sessions stored in Redis, not in application memory
|
||||||
|
- **Tool Support**: Easy integration with Swagger UI for API documentation
|
||||||
|
- **Industry Standard**: Familiar to developers, extensive ecosystem support
|
||||||
|
|
||||||
|
## 7. Implemented API Endpoints
|
||||||
|
|
||||||
|
### Authentication (`/api/v1/auth`)
|
||||||
|
```rust
|
||||||
|
POST /api/v1/auth/login // Login with username/password
|
||||||
|
POST /api/v1/auth/logout // Logout and clear session
|
||||||
|
```
|
||||||
|
|
||||||
|
### Users (`/api/v1/user`)
|
||||||
|
```rust
|
||||||
|
GET /api/v1/user // Get all users
|
||||||
|
GET /api/v1/user/{id} // Get specific user
|
||||||
|
POST /api/v1/user // Create user (with password)
|
||||||
|
DELETE /api/v1/user/{id} // Delete user
|
||||||
|
```
|
||||||
|
|
||||||
|
### Projects (`/api/v1/project`)
|
||||||
|
```rust
|
||||||
|
GET /api/v1/project // Get all projects
|
||||||
|
GET /api/v1/project/{id} // Get specific project
|
||||||
|
POST /api/v1/project // Create project
|
||||||
|
PUT /api/v1/project/{id} // Update project
|
||||||
|
DELETE /api/v1/project/{id} // Delete project
|
||||||
|
```
|
||||||
|
|
||||||
|
### Groups (`/api/v1/group`) - Stubs implemented
|
||||||
|
```rust
|
||||||
|
GET /api/v1/group // Not implemented (returns 501)
|
||||||
|
GET /api/v1/group/{project} // Not implemented
|
||||||
|
POST /api/v1/group // Not implemented
|
||||||
|
PUT /api/v1/group // Not implemented
|
||||||
|
DELETE /api/v1/group/{id} // Not implemented
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. Security Implementation
|
||||||
|
|
||||||
|
### Password Security:
|
||||||
|
```rust
|
||||||
|
// From user.rs
|
||||||
|
- Argon2 hashing with salt generation
|
||||||
|
- Password validation (minimum 8 characters)
|
||||||
|
- Secure password verification on login
|
||||||
|
```
|
||||||
|
|
||||||
|
### Session Management:
|
||||||
|
```rust
|
||||||
|
// From main.rs
|
||||||
|
- Redis-based sessions with actix-session
|
||||||
|
- Secure cookies (HTTPS in production)
|
||||||
|
- Session purging on logout
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Handling:
|
||||||
|
```rust
|
||||||
|
// From error.rs
|
||||||
|
pub enum ApiError {
|
||||||
|
Database(#[from] sea_orm::DbErr),
|
||||||
|
Unauthorized,
|
||||||
|
NotFound,
|
||||||
|
BadRequest(String),
|
||||||
|
ValidationError(#[from] validator::ValidationErrors),
|
||||||
|
Argon2Error(String),
|
||||||
|
SessionInsertError(#[from] actix_session::SessionInsertError),
|
||||||
|
AlreadyLoggedIn,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. Testing Strategy
|
||||||
|
|
||||||
|
### Unit Tests ✅
|
||||||
|
Located in individual modules, for example:
|
||||||
|
```rust
|
||||||
|
// From main.rs tests
|
||||||
|
#[test]
|
||||||
|
fn build_database_url_with_defaults() { ... }
|
||||||
|
#[test]
|
||||||
|
fn build_database_url_with_all_vars() { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration Tests ✅
|
||||||
|
Located in `crates/backend/tests/`:
|
||||||
|
```rust
|
||||||
|
// From integration_tests.rs
|
||||||
|
#[actix_web::test]
|
||||||
|
async fn test_ok() { ... }
|
||||||
|
|
||||||
|
// From endpoints/user.rs
|
||||||
|
#[actix_web::test]
|
||||||
|
async fn test_create_user() { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Infrastructure:
|
||||||
|
- **Testcontainers**: Automated PostgreSQL and Redis containers for testing
|
||||||
|
- **Test Helpers**: Reusable test app setup with `create_test_app!` macro
|
||||||
|
- **Database Migrations**: Automatic migration in test setup
|
||||||
|
|
||||||
|
### No E2E Tests (Could-Have)
|
||||||
|
As you mentioned, E2E tests are not implemented but would fall under the same category as integration tests.
|
||||||
|
|
||||||
|
## 10. Working Examples
|
||||||
|
|
||||||
|
### Login Request:
|
||||||
|
```json
|
||||||
|
// POST /api/v1/auth/login
|
||||||
|
{
|
||||||
|
"username": "teacher1",
|
||||||
|
"password": "securepassword"
|
||||||
|
}
|
||||||
|
// Response: 200 OK
|
||||||
|
{
|
||||||
|
"message": "Login successful"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create User:
|
||||||
|
```json
|
||||||
|
// POST /api/v1/user
|
||||||
|
{
|
||||||
|
"username": "newteacher",
|
||||||
|
"name": "New Teacher",
|
||||||
|
"password": "password123"
|
||||||
|
}
|
||||||
|
// Response: 200 OK
|
||||||
|
{
|
||||||
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"username": "newteacher",
|
||||||
|
"name": "New Teacher"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create Project:
|
||||||
|
```json
|
||||||
|
// POST /api/v1/project
|
||||||
|
{
|
||||||
|
"name": "Math Group Project 2024"
|
||||||
|
}
|
||||||
|
// Response: 200 OK
|
||||||
|
{
|
||||||
|
"id": "660e8400-e29b-41d4-a716-446655440001",
|
||||||
|
"name": "Math Group Project 2024"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 11. Future Enhancements
|
||||||
|
|
||||||
|
### Planned Features (from stubs):
|
||||||
|
- Group management implementation
|
||||||
|
- Class management system
|
||||||
|
- Template system for reusable configurations
|
||||||
|
- LDAP authentication integration (code exists in `crates/ldap/`)
|
||||||
|
|
||||||
|
### Potential Improvements:
|
||||||
|
- WebSocket support for real-time updates
|
||||||
|
- Batch operations for bulk user/group creation
|
||||||
|
- Export functionality for grades
|
||||||
|
- Email notifications for group assignments
|
||||||
|
|
||||||
|
## 12. Conclusion
|
||||||
|
|
||||||
|
The PGG API successfully provides a secure, type-safe foundation for peer group grading management. Using Rust with Actix-web ensures high performance and reliability, while Sea-ORM provides a robust database abstraction layer. The modular architecture allows for easy extension, and the comprehensive test suite ensures reliability. With session-based authentication and proper error handling, the API is ready for production use in educational environments.
|
||||||
Loading…
Add table
Reference in a new issue