Operations-Focused Routers
===========================

Routers primarily serving observatory automation with critical operations buffering.

.. contents:: Table of Contents
   :local:
   :depth: 2

Executed Obs Units Router
--------------------------

**Path**: ``/executed_obs_units``

**Purpose**: Record actual telescope observations

**Key endpoints**:

* ``POST /start`` - Start observation (buffered)
* ``PUT /{id}/finish`` - Finish observation (buffered)
* ``GET /{obs_unit_id}`` - Query observations (smart query)

**Example from code**:

.. literalinclude:: ../../../ccat_ops_db_api/routers/executed_obs_units.py
   :language: python
   :lines: 40-90
   :emphasize-lines: 1-5, 20-25

**Characteristics**:

* ``@critical_operation`` decorator
* Pre-generated UUIDs
* Smart queries merge buffer + database
* High reliability requirement

Raw Data Files Router
---------------------

**Path**: ``/raw_data_files``

**Purpose**: Register data files produced by instruments

**Key endpoints**:

* ``POST /`` - Register file (buffered)
* ``POST /bulk`` - Register multiple files (buffered)
* ``GET /{id}`` - Get file metadata

**Example**:

.. code-block:: python

   @router.post("/bulk")
   @critical_operation
   async def register_files_bulk(
       files: List[RawDataFileCreate],
       _transaction_builder = Depends(get_transaction_builder)
   ):
       # Bulk create step
       files_step = _transaction_builder.bulk_create(
           model_class=models.RawDataFile,
           data_list=[f.dict() for f in files],
           step_id="bulk_create_files"
       )
       
       return {"count": len(files), "status": "buffered"}

Raw Data Package Router
-----------------------

**Path**: ``/raw_data_package``

**Purpose**: Group related data files

**Key endpoints**:

* ``POST /`` - Create package (buffered)
* ``GET /{id}`` - Get package with files
* ``PUT /{id}/finalize`` - Mark complete

**Characteristics**:

* Groups files by observation
* Size limits (50GB max recommended)
* Status tracking (building → complete)

Staging Router
--------------

**Path**: ``/staging``

**Purpose**: Data staging for transfer

**Key endpoints**:

* ``POST /stage`` - Request staging (buffered)
* ``GET /status/{id}`` - Check status
* ``DELETE /{id}`` - Cancel staging

Next Steps
----------

* :doc:`shared-routers` - Shared routers
* :doc:`../../tutorials/observatory-integration/recording-observations` - Using in scripts