backend-conventions

Generation Placement#

Read .cob/feature-layout.json first; preserve it. Without a marker use cob's existing legacy-tree detection, otherwise bundle. Follow the generation placement contract. Generate feature/<d>/server/lib/src/{endpoint,service,model,…} in <d>_server (type: module) and feature/<d>/client in <d>_client; bundle.json owns assembly, host-integration.json owns host contracts. Legacy placement applies only to that resolved layout.

The host owns assembly, auth providers, cross-feature work and DB integration tests. Module pure tests stay in server/test/unit/; Session/withServerpod/DB tests go to backend/<project>_server/test/integration/ and bundle.json.hostTests. Session-aware bind(serverpod, …) / forSession(session) ports and unimplemented adapters fail closed. New default is official 4.0.3; codegen is dependency modules → feature module → host.

Layer Structure#

• Endpoint → Service → Entity.db (별도 Repository 계층은 선택 — kobic 백엔드는 미사용)
• No business logic in Endpoints
• No direct DB queries in Endpoints
• No direct calls between Repositories (coordinate in Services)

Endpoint Rules#

• Separate App endpoints and Console endpoints
• Use requireLogin => true when authentication is required
• Method names: Use get, list, create, update, delete prefixes

Model Rules#

• Required fields on all Entities: createdAt: DateTime, updatedAt: DateTime?
• Add Korean comments (###) on all fields
• Foreign keys must have indexes
• DTOs must be separate from Entities (_create_request, _update_request, _list_response)

Transaction Rules#

• Use tx inside transactions (not session)
• Always wrap multiple DB operations in a transaction
• Transaction management only in the Service layer

Caching Rules#

• Always set lifetime
• Invalidate related caches when entities are modified
• Use global cache in multi-server environments

Testing Rules#

• Call endpoints via the endpoints parameter
• Authentication tests: three cases — authenticated/unauthenticated/insufficient permissions
• Concurrent transaction tests: rollbackDatabase: disabled

Logging Rules#

• Do not log sensitive data
• Always close InternalSession
• Do not use a session after it is closed

Code Generation#

• Always run serverpod generate after modifying .spy.yaml
• Always run serverpod create-migration after Entity changes
• Commit after migrations are applied