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