app_layer_rules

Purpose and Scope

• The App layer is the HTTP boundary for the backend. It applies to files under backend/apps/*.py.
• Responsibilities:
  • Parse and validate HTTP inputs.
  • Call underlying services; do not implement core business logic here.
  • Translate domain/service exceptions into HTTPException with proper status codes.
  • Return JSONResponse(status_code=HTTPStatus.OK, content=payload) on success.
• Configuration: Do not access environment variables directly. Read configuration via consts.const or pass values through from the request to services.

References: backend/consts/exceptions.py

Routing and URL Design

• Keep existing top-level prefixes for compatibility (e.g., "/agent", "/memory"). When adding new modules or endpoints, follow these rules:
  • Use plural nouns for collection-style resources (e.g., "/agents", "/memories").
  • Use snake_case for all path segments. Avoid hyphens and camelCase.
  • Prefer resource-oriented paths for CRUD-style operations. Example: "/agents" (collection), "/agents/{agent_id}" (single resource).
  • Use action-style paths only when necessary to match current patterns or when the operation is not naturally CRUD (e.g., "/agent/run", "/agent/stop/{conversation_id}").
  • Path parameters must be singular, semantic nouns: "/agents/{agent_id}", "/memories/{memory_id}".
  • Keep backwards compatibility: do not rename existing routes; new routes should follow these conventions.

HTTP Methods

• GET: Read and list operations only. Maintain existing special cases where GET performs safe actions (e.g., GET /agent/stop/{conversation_id}), but do not introduce new side-effecting GETs.
• POST: Create resources, perform searches, or trigger actions with side effects (e.g., POST /memory/add, POST /memory/search, POST /agent/run).
• DELETE: Delete resources or clear collections (e.g., DELETE /memory/clear). Ensure idempotency.
• PUT/PATCH: Update resources. Prefer PUT for full updates and PATCH for partial updates. Preserve legacy POST /update endpoints for compatibility but favor PUT/PATCH for new code.