Organize backend into layered architecture (#124) #125
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* refactor(backend): implement layered architecture pattern Add enterprise-level separation of concerns with three new layers: Repository Layer (app/repositories/): - BaseRepository with generic CRUD operations - AssignmentRepository, PersonRepository, BlockRepository - AbsenceRepository, UserRepository - Pure database operations abstracted from business logic Service Layer (app/services/): - AssignmentService with ACGME validation integration - PersonService, BlockService, AbsenceService - AuthService for authentication business logic - Services use repositories as building blocks Controller Layer (app/controllers/): - AssignmentController, PersonController, BlockController - AbsenceController, AuthController - Handle request validation and HTTP status codes - Build response bodies with proper error handling Route Refactoring: - Routes now act as thin routing layer - Connect URL paths to controllers - Retain auth middleware (FastAPI Depends) - No business logic in route handlers This architecture improves: - Testability: Each layer can be unit tested in isolation - Maintainability: Clear separation of concerns - Scalability: Easy to add new features following patterns - Auditability: Clear trace from rules to code * docs: add comprehensive resilience framework for scheduling system Synthesizes concepts from cross-industry domains to build robust scheduling system capable of handling severe faculty shortages (e.g., PCS season): - Queuing Theory: 80% utilization threshold to prevent cascade failures - Nuclear Engineering: Defense in depth with 5 safety levels - Power Grid: N-1/N-2 contingency planning and phase transition warnings - AWS Architecture: Static stability and blast radius isolation - Biology: Homeostasis, allostatic load tracking, feedback loops - Chemistry: Le Chatelier's principle for stress response prediction - Psychology: Cognitive load management and decision fatigue mitigation - Network Theory: Hub vulnerability analysis - Swarm Intelligence: Stigmergy-based preference systems Includes prioritized implementation roadmap, load shedding protocol, sacrifice hierarchy, and risk/benefit analysis for each concept. --------- Co-authored-by: Claude <noreply@anthropic.com>
Euda1mon1a
merged commit f94e964
into
claude/backend-layered-architecture-BQqmz
5 checks passed
Euda1mon1a
added a commit
that referenced
this pull request
Dec 16, 2025
* refactor(backend): implement layered architecture pattern
Add enterprise-level separation of concerns with three new layers:
Repository Layer (app/repositories/):
- BaseRepository with generic CRUD operations
- AssignmentRepository, PersonRepository, BlockRepository
- AbsenceRepository, UserRepository
- Pure database operations abstracted from business logic
Service Layer (app/services/):
- AssignmentService with ACGME validation integration
- PersonService, BlockService, AbsenceService
- AuthService for authentication business logic
- Services use repositories as building blocks
Controller Layer (app/controllers/):
- AssignmentController, PersonController, BlockController
- AbsenceController, AuthController
- Handle request validation and HTTP status codes
- Build response bodies with proper error handling
Route Refactoring:
- Routes now act as thin routing layer
- Connect URL paths to controllers
- Retain auth middleware (FastAPI Depends)
- No business logic in route handlers
This architecture improves:
- Testability: Each layer can be unit tested in isolation
- Maintainability: Clear separation of concerns
- Scalability: Easy to add new features following patterns
- Auditability: Clear trace from rules to code
* docs: add comprehensive resilience framework for scheduling system
Synthesizes concepts from cross-industry domains to build robust scheduling
system capable of handling severe faculty shortages (e.g., PCS season):
- Queuing Theory: 80% utilization threshold to prevent cascade failures
- Nuclear Engineering: Defense in depth with 5 safety levels
- Power Grid: N-1/N-2 contingency planning and phase transition warnings
- AWS Architecture: Static stability and blast radius isolation
- Biology: Homeostasis, allostatic load tracking, feedback loops
- Chemistry: Le Chatelier's principle for stress response prediction
- Psychology: Cognitive load management and decision fatigue mitigation
- Network Theory: Hub vulnerability analysis
- Swarm Intelligence: Stigmergy-based preference systems
Includes prioritized implementation roadmap, load shedding protocol,
sacrifice hierarchy, and risk/benefit analysis for each concept.
* feat(resilience): implement Tier 1 critical resilience framework
Implements the 5 critical concepts from the resilience framework:
1. Utilization Threshold (Queuing Theory)
- 80% max utilization cap to prevent cascade failures
- Wait time multiplier calculation (M/M/1 queue)
- Utilization forecasting with known absences
- 5-level status system (GREEN to BLACK)
2. Defense in Depth (Nuclear Engineering)
- 5 safety levels: Prevention, Control, Safety Systems,
Containment, Emergency Response
- N+2 redundancy checking for critical functions
- Action handlers for automated responses
- Level-appropriate response recommendations
3. N-1/N-2 Contingency Analysis (Power Grid)
- Single faculty loss simulation (N-1)
- Pair loss simulation (N-2) for critical periods
- Centrality scoring for hub vulnerability
- Phase transition risk detection
4. Static Stability (AWS Architecture)
- Pre-computed fallback schedules for 7 scenarios
- Scheduling zones for blast radius isolation
- Instant fallback activation (no crisis computation)
- Zone health monitoring
5. Sacrifice Hierarchy (Triage Medicine)
- 7-level activity priority (Patient Safety to Optional Education)
- Load shedding levels (NORMAL to CRITICAL)
- Automatic shed_load() calculation
- Recovery planning in reverse order
Includes ResilienceService to orchestrate all components with:
- Unified health checking
- Crisis response activation/deactivation
- Event handlers for monitoring
- Comprehensive reporting
* Organize backend into layered architecture (#124) (#125)
* refactor(backend): implement layered architecture pattern
Add enterprise-level separation of concerns with three new layers:
Repository Layer (app/repositories/):
- BaseRepository with generic CRUD operations
- AssignmentRepository, PersonRepository, BlockRepository
- AbsenceRepository, UserRepository
- Pure database operations abstracted from business logic
Service Layer (app/services/):
- AssignmentService with ACGME validation integration
- PersonService, BlockService, AbsenceService
- AuthService for authentication business logic
- Services use repositories as building blocks
Controller Layer (app/controllers/):
- AssignmentController, PersonController, BlockController
- AbsenceController, AuthController
- Handle request validation and HTTP status codes
- Build response bodies with proper error handling
Route Refactoring:
- Routes now act as thin routing layer
- Connect URL paths to controllers
- Retain auth middleware (FastAPI Depends)
- No business logic in route handlers
This architecture improves:
- Testability: Each layer can be unit tested in isolation
- Maintainability: Clear separation of concerns
- Scalability: Easy to add new features following patterns
- Auditability: Clear trace from rules to code
* docs: add comprehensive resilience framework for scheduling system
Synthesizes concepts from cross-industry domains to build robust scheduling
system capable of handling severe faculty shortages (e.g., PCS season):
- Queuing Theory: 80% utilization threshold to prevent cascade failures
- Nuclear Engineering: Defense in depth with 5 safety levels
- Power Grid: N-1/N-2 contingency planning and phase transition warnings
- AWS Architecture: Static stability and blast radius isolation
- Biology: Homeostasis, allostatic load tracking, feedback loops
- Chemistry: Le Chatelier's principle for stress response prediction
- Psychology: Cognitive load management and decision fatigue mitigation
- Network Theory: Hub vulnerability analysis
- Swarm Intelligence: Stigmergy-based preference systems
Includes prioritized implementation roadmap, load shedding protocol,
sacrifice hierarchy, and risk/benefit analysis for each concept.
---------
Co-authored-by: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Euda1mon1a
added a commit
that referenced
this pull request
Dec 22, 2025
* refactor(backend): implement layered architecture pattern
Add enterprise-level separation of concerns with three new layers:
Repository Layer (app/repositories/):
- BaseRepository with generic CRUD operations
- AssignmentRepository, PersonRepository, BlockRepository
- AbsenceRepository, UserRepository
- Pure database operations abstracted from business logic
Service Layer (app/services/):
- AssignmentService with ACGME validation integration
- PersonService, BlockService, AbsenceService
- AuthService for authentication business logic
- Services use repositories as building blocks
Controller Layer (app/controllers/):
- AssignmentController, PersonController, BlockController
- AbsenceController, AuthController
- Handle request validation and HTTP status codes
- Build response bodies with proper error handling
Route Refactoring:
- Routes now act as thin routing layer
- Connect URL paths to controllers
- Retain auth middleware (FastAPI Depends)
- No business logic in route handlers
This architecture improves:
- Testability: Each layer can be unit tested in isolation
- Maintainability: Clear separation of concerns
- Scalability: Easy to add new features following patterns
- Auditability: Clear trace from rules to code
* docs: add comprehensive resilience framework for scheduling system
Synthesizes concepts from cross-industry domains to build robust scheduling
system capable of handling severe faculty shortages (e.g., PCS season):
- Queuing Theory: 80% utilization threshold to prevent cascade failures
- Nuclear Engineering: Defense in depth with 5 safety levels
- Power Grid: N-1/N-2 contingency planning and phase transition warnings
- AWS Architecture: Static stability and blast radius isolation
- Biology: Homeostasis, allostatic load tracking, feedback loops
- Chemistry: Le Chatelier's principle for stress response prediction
- Psychology: Cognitive load management and decision fatigue mitigation
- Network Theory: Hub vulnerability analysis
- Swarm Intelligence: Stigmergy-based preference systems
Includes prioritized implementation roadmap, load shedding protocol,
sacrifice hierarchy, and risk/benefit analysis for each concept.
* feat(resilience): implement Tier 1 critical resilience framework
Implements the 5 critical concepts from the resilience framework:
1. Utilization Threshold (Queuing Theory)
- 80% max utilization cap to prevent cascade failures
- Wait time multiplier calculation (M/M/1 queue)
- Utilization forecasting with known absences
- 5-level status system (GREEN to BLACK)
2. Defense in Depth (Nuclear Engineering)
- 5 safety levels: Prevention, Control, Safety Systems,
Containment, Emergency Response
- N+2 redundancy checking for critical functions
- Action handlers for automated responses
- Level-appropriate response recommendations
3. N-1/N-2 Contingency Analysis (Power Grid)
- Single faculty loss simulation (N-1)
- Pair loss simulation (N-2) for critical periods
- Centrality scoring for hub vulnerability
- Phase transition risk detection
4. Static Stability (AWS Architecture)
- Pre-computed fallback schedules for 7 scenarios
- Scheduling zones for blast radius isolation
- Instant fallback activation (no crisis computation)
- Zone health monitoring
5. Sacrifice Hierarchy (Triage Medicine)
- 7-level activity priority (Patient Safety to Optional Education)
- Load shedding levels (NORMAL to CRITICAL)
- Automatic shed_load() calculation
- Recovery planning in reverse order
Includes ResilienceService to orchestrate all components with:
- Unified health checking
- Crisis response activation/deactivation
- Event handlers for monitoring
- Comprehensive reporting
* Organize backend into layered architecture (#124) (#125)
* refactor(backend): implement layered architecture pattern
Add enterprise-level separation of concerns with three new layers:
Repository Layer (app/repositories/):
- BaseRepository with generic CRUD operations
- AssignmentRepository, PersonRepository, BlockRepository
- AbsenceRepository, UserRepository
- Pure database operations abstracted from business logic
Service Layer (app/services/):
- AssignmentService with ACGME validation integration
- PersonService, BlockService, AbsenceService
- AuthService for authentication business logic
- Services use repositories as building blocks
Controller Layer (app/controllers/):
- AssignmentController, PersonController, BlockController
- AbsenceController, AuthController
- Handle request validation and HTTP status codes
- Build response bodies with proper error handling
Route Refactoring:
- Routes now act as thin routing layer
- Connect URL paths to controllers
- Retain auth middleware (FastAPI Depends)
- No business logic in route handlers
This architecture improves:
- Testability: Each layer can be unit tested in isolation
- Maintainability: Clear separation of concerns
- Scalability: Easy to add new features following patterns
- Auditability: Clear trace from rules to code
* docs: add comprehensive resilience framework for scheduling system
Synthesizes concepts from cross-industry domains to build robust scheduling
system capable of handling severe faculty shortages (e.g., PCS season):
- Queuing Theory: 80% utilization threshold to prevent cascade failures
- Nuclear Engineering: Defense in depth with 5 safety levels
- Power Grid: N-1/N-2 contingency planning and phase transition warnings
- AWS Architecture: Static stability and blast radius isolation
- Biology: Homeostasis, allostatic load tracking, feedback loops
- Chemistry: Le Chatelier's principle for stress response prediction
- Psychology: Cognitive load management and decision fatigue mitigation
- Network Theory: Hub vulnerability analysis
- Swarm Intelligence: Stigmergy-based preference systems
Includes prioritized implementation roadmap, load shedding protocol,
sacrifice hierarchy, and risk/benefit analysis for each concept.
---------
Co-authored-by: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add enterprise-level separation of concerns with three new layers:
Repository Layer (app/repositories/):
Service Layer (app/services/):
Controller Layer (app/controllers/):
Route Refactoring:
This architecture improves:
Synthesizes concepts from cross-industry domains to build robust scheduling system capable of handling severe faculty shortages (e.g., PCS season):
Includes prioritized implementation roadmap, load shedding protocol, sacrifice hierarchy, and risk/benefit analysis for each concept.