Server Update & Responsibility Tracker - Phase 3 Backend

This is the Phase 3 backend implementation for the Server Update & Responsibility Tracker project, building on Phases 1+2 with service window safety evaluation.

Features Implemented

Phase 1 Features (Retained)

• JWT-based authentication with access and refresh tokens
• Argon2 password hashing
• Core data models and permissions
• Server management endpoints
• Responsibility management

Phase 2 Features (Retained)

• Update Status Evaluation: Deterministic calculation of update urgency
• Computed Status Fields: Real-time evaluation without database storage
• Status Logic: "ok" | "due" | "overdue" based on schedule intervals
• Warning Threshold: 20% of interval_days (minimum 1 day, rounded up)
• UTC Timezone Handling: All calculations use UTC, timezone-agnostic

Phase 3 New Features

• Service Window Evaluation: Time-of-day safety assessment
• Timezone-Aware Logic: Per-server timezone handling using IANA strings
• Window Types: Support for same-day and overnight service windows
• Safety Status: "safe" | "risky" | "unknown" based on current local time
• Transparent Debugging: Server local time included in responses

Data Models (Unchanged)

• User: id, username, email, password_hash, created_at
• UpdateSchedule: id, name, interval_days, preferred_weekday
• Server: id, name, hostname, ip_address, description, update_schedule_id, last_updated_at, last_rebooted_at, service_window_start, service_window_end, timezone, created_by, created_at
• ServerUser: server_id, user_id, role (owner/maintainer)

Update Status Logic (Phase 2)

interval_days = update_schedule.interval_days
due_at = last_updated_at + interval_days
warning_threshold = max(1, ceil(interval_days * 0.2))

Status Rules:
- now < due_at - warning_threshold → "ok"
- now >= due_at - warning_threshold → "due"  
- now > due_at → "overdue"
- last_updated_at = NULL → "overdue"

Service Window Logic (Phase 3)

Convert now_utc → server_local_time using IANA timezone

Status Rules:
- Missing config (start/end/timezone) → "unknown"
- Invalid timezone string → "unknown"
- Current local time inside service window → "risky"
- Current local time outside service window → "safe"

Window Types:
- Same-day: 08:00 → 22:00 (risky if 08:00 <= now < 22:00)
- Overnight: 22:00 → 08:00 (risky if now >= 22:00 OR now < 08:00)

API Endpoints

• Auth: POST /auth/login, POST /auth/refresh, POST /auth/logout
• Users: GET /users/me, GET /users
• Servers: GET /servers, GET /servers/{id}, POST /servers, PATCH /servers/{id}
• Responsibilities: POST /servers/{id}/users, DELETE /servers/{id}/users/{user_id}

Enhanced Server Responses

All server GET endpoints now include computed fields:

Phase 2 Fields:

• update_status: "ok" | "due" | "overdue"
• next_update_due_at: UTC timestamp when next update is due
• days_since_last_update: Integer days since last update

Phase 3 Fields:

• service_window_status: "safe" | "risky" | "unknown"
• server_local_time: Server's local time for transparency/debugging

Setup

1. Install dependencies:

pip install -r requirements.txt

2. Configure environment:

cp .env.example .env
# Edit .env with your database URL and secret key

3. Set up database:

# Create PostgreSQL database
# Run Alembic migrations (once dependencies are installed)

4. Run the application:

uvicorn main:app --reload

5. Access API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Phase Boundaries

This implementation strictly follows Phase 3 scope:

✅ Phase 1 Included:

• Authentication and authorization
• Core data models
• Permission enforcement
• Read-only server visibility
• JSON-only API endpoints

✅ Phase 2 Added:

• Update status calculation (read-only)
• Schedule-based due/overdue logic
• Computed status fields in API responses
• Deterministic, testable evaluation

✅ Phase 3 Added:

• Service window safety evaluation (read-only)
• Timezone-aware local time assessment
• Same-day and overnight window support
• Computed safety status in API responses
• Transparent server local time for debugging

❌ Explicitly Excluded:

• Frontend implementation
• Update blocking or enforcement
• Automation or scheduling
• Notifications or alerts
• Background jobs/cron workers
• Persisting service window status
• AI features
• LDAP/SSO

Phase 4 Boundaries (Future)

The following are reserved for future phases:

• UI warnings, confirmations, visual indicators
• Update scheduling automation
• Policy enforcement
• Integration with monitoring systems

The system can answer both "Does this server need an update?" and "Is it safe to update right now?" but does not block actions or make automated decisions.