# Journals API Migration Plan

This document outlines the plan for migrating the Journals API to the new, standardized Aether API architecture.

## 1. Current API Analysis

The Journals module consists of two main objects: `journal` and `journal_entry`. Currently, these objects are primarily accessed through the generic CRUD endpoints.

### How the Front-End Likely Interacts with the API:

*   **Create a Journal:**
    *   `POST /v2/crud/journal`
    *   **Body:** A JSON object with all the fields from the `Journal_Base` model.

*   **Get a Journal:**
    *   `GET /v2/crud/journal/{journal_id_random}`

*   **List Journals:**
    *   `GET /v2/crud/journal/list`
    *   This would also likely use the `for_obj_type` and `for_obj_id` query parameters to get journals for a specific person or account (e.g., `GET /v2/crud/journal/list?for_obj_type=person&for_obj_id={person_id_random}`).

*   **Update a Journal:**
    *   `PATCH /v2/crud/journal/{journal_id_random}`
    *   **Body:** A JSON object with the fields to be updated.

*   **Delete a Journal:**
    *   `DELETE /v2/crud/journal/{journal_id_random}`

The same patterns apply to the `journal_entry` object.

## 2. Proposed New API

The new Journals API will be more explicit, organized, and easier to use. It will follow the new architectural principles of the Aether API rewrite.

### New URL Structure:

*   `/journals/`
*   `/journals/{journal_id_random}`
*   `/journals/{journal_id_random}/entries/`
*   `/journals/{journal_id_random}/entries/{entry_id_random}`

### New Models:

We will create new, simplified models for `Journal` and `JournalEntry` that inherit from the `CoreObject` base model.

*   `app/models/journal.py`:
    *   `JournalBase(CoreObject)`
    *   `Journal(JournalBase)`
    *   `JournalInDB(Journal, CoreObjectInDB)`
    *   `JournalCreate(JournalBase)`
    *   `JournalUpdate(JournalBase)`
*   `app/models/journal_entry.py`:
    *   `JournalEntryBase(CoreObject)`
    *   `JournalEntry(JournalEntryBase)`
    *   `JournalEntryInDB(JournalEntry, CoreObjectInDB)`
    *   `JournalEntryCreate(JournalEntryBase)`
    *   `JournalEntryUpdate(JournalEntryBase)`

### New Endpoints:

A new `app/routers/journals.py` router will be created with the following explicit endpoints:

*   `POST /journals/`: Create a new journal.
*   `GET /journals/`: List all journals (with query params for filtering).
*   `GET /journals/{journal_id_random}`: Get a single journal by its `id_random`.
*   `PATCH /journals/{journal_id_random}`: Update a journal.
*   `DELETE /journals/{journal_id_random}`: Delete a journal.
*   `POST /journals/{journal_id_random}/entries/`: Create a new journal entry for a specific journal.
*   `GET /journals/{journal_id_random}/entries/`: List all entries for a specific journal.
*   `GET /journals/{journal_id_random}/entries/{entry_id_random}`: Get a single journal entry.
*   `PATCH /journals/{journal_id_random}/entries/{entry_id_random}`: Update a journal entry.
*   `DELETE /journals/{journal_id_random}/entries/{entry_id_random}`: Delete a journal entry.

## 3. Side-by-Side Comparison

| Operation | Current API Call | Proposed New API Call |
| --- | --- | --- |
| Create Journal | `POST /v2/crud/journal` | `POST /journals/` |
| Get Journal | `GET /v2/crud/journal/{id}` | `GET /journals/{id}` |
| List Journals | `GET /v2/crud/journal/list` | `GET /journals/` |
| Update Journal | `PATCH /v2/crud/journal/{id}` | `PATCH /journals/{id}` |
| Delete Journal | `DELETE /v2/crud/journal/{id}` | `DELETE /journals/{id}` |
| Create Entry | `POST /v2/crud/journal_entry` (with `journal_id_random` in body) | `POST /journals/{journal_id}/entries/` |
| List Entries | `GET /v2/crud/journal_entry/list?for_obj_type=journal&for_obj_id={id}` | `GET /journals/{journal_id}/entries/` |

This plan provides a clear path forward for refactoring the Journals module. By following this plan, we can create a more maintainable and user-friendly API while ensuring a smooth transition for the front-end.