ortools review on some design issues and fixed flaky test

README.md

@@ -76,6 +76,20 @@ implementations in an outer adapter. For future calculations, define a port in
 `service.port` using domain types and implement it in `solver`; services must not
 depend on solver implementations or expose OR-Tools types.
 
+Handwritten production types each have their own file and must be top-level.
+Service records live in `service.model`; the school JSON snapshot records and
+import preview are service-owned data models. Scheduling records shared with
+the solver live in `model.scheduling`. Each group requirement combines its group
+ID and appearance count in one record.
+
+`service.port.SchedulingEngine` is the application-owned interface for solving a
+scheduling problem. `SchedulingService` calls this interface; dependency injection
+supplies `solver.OrToolsSchedulingEngine`. The port accepts and returns domain
+types, so neither the caller nor the contract depends on OR-Tools or the concrete
+school-management service. Architecture tests enforce the port's location and
+dependencies, the location of service records, and the top-level type rule
+(excluding generated Lombok builders and compiler helpers).
+
 
 ## School management REST API