# Aether API V3 Implementation Plan

This document outlines the plan to build the Aether API V3. The goal of V3 is to create a new, modern, and consistent set of API endpoints that will run in parallel with the existing legacy endpoints. No existing endpoints will be modified or deleted.

## V3 Architecture

The V3 API will be centered around a new generic CRUD router that implements a hierarchical, nested URL structure for parent-child object relationships.

- **Endpoint Prefix:** All new endpoints will be under `/v3/crud/`.
- **Top-Level Objects:** Handled via a flat URL structure.
  - `GET /v3/crud/journal/`
  - `POST /v3/crud/journal/`
  - `GET /v3/crud/journal/{journal_id}`
- **Child Objects:** Handled via a nested URL structure that enforces the parent-child relationship.
  - `GET /v3/crud/journal/{journal_id}/journal_entry/`
  - `POST /v3/crud/journal/{journal_id}/journal_entry/`
  - `GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`

This structure will be implemented in a new `app/routers/api_crud_v3.py` file, which will be inspired by the logic in the existing `api_crud_v2.py` but with updated routing to handle the nesting.

## Implementation Phases

### Phase 1: Create Stub V3 Endpoint (Proof-of-Concept)

The first step is to create a minimal, non-functional "stub" endpoint to prove that the basic routing and application integration works.

1.  **Create File:** Create a new file: `app/routers/api_crud_v3.py`.
2.  **Add Stub Endpoint:** Add a simple health-check or "hello world" endpoint within this file, for example, a `GET` endpoint at `/v3/crud/health`.
3.  **Update Main App:** In `app/main.py`, import and include the new V3 router.

### Phase 2: Implement Top-Level Object CRUD

Using `journal` as the first test case, implement the full set of CRUD operations for a top-level object.

-   `GET /v3/crud/journal/`
-   `POST /v3/crud/journal/`
-   `GET /v3/crud/journal/{journal_id}`
-   `PATCH /v3/crud/journal/{journal_id}`
-   `DELETE /v3/crud/journal/{journal_id}`

### Phase 3: Implement Nested Object CRUD

Using `journal_entry` as the first test case, implement the full set of CRUD operations for a child object, ensuring the `journal_id` from the URL is used for filtering.

-   `GET /v3/crud/journal/{journal_id}/journal_entry/`
-   `POST /v3/crud/journal/{journal_id}/journal_entry/`
-   `GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`
-   `PATCH /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`
-   `DELETE /v3/crud/journal/{journal_id}/journal_entry/{entry_id}`

### Phase 4: Incremental Rollout

Once the patterns for top-level and nested objects are proven with Journal and Journal Entry, we will apply the same pattern to other Aether objects in batches.