Related Components
==================

.. verified:: 2025-01-21
   :reviewer: Christof Buchbender

ops-db is the database schema and ORM layer that serves as the foundation for several
other CCAT components. This page provides links to related documentation.

Related Components
------------------

ops-db-api
^^^^^^^^^^

The ops-db-api provides a RESTful API for programmatic access to the operations database.
Instrument teams and automated systems use this API to:

* Register observations and data files
* Query observation status
* Update data package states
* Manage long-term archive transfers

**Documentation:** :doc:`/ops-db-api/docs/index`

ops-db-ui
^^^^^^^^^

The ops-db-ui is a Vue.js web interface for browsing and managing operations database
records. It provides:

* Web-based browsing of observations and data packages
* Visualization of data flow and transfer status
* User-friendly access to database records
* Monitoring dashboards for system health

**Documentation:** :doc:`/ops-db-ui/docs/index`

data-transfer
^^^^^^^^^^^^^

The data-transfer package orchestrates the actual movement of data files based on records
in ops-db. It:

* Reads transfer routes and schedules from ops-db
* Performs file transfers using BBCP, S3, or other methods
* Updates transfer status and physical copy records
* Manages long-term archive and staging operations

**Documentation:** :doc:`/data-transfer/docs/index`

**Key Integration Points:**

* data-transfer reads :py:class:`~ccat_ops_db.models.DataTransferRoute`,
  :py:class:`~ccat_ops_db.models.DataTransferPackage`, and
  :py:class:`~ccat_ops_db.models.LongTermArchiveTransfer` records
* data-transfer updates :py:class:`~ccat_ops_db.models.Status`,
  :py:class:`~ccat_ops_db.models.PhysicalCopy`, and
  :py:class:`~ccat_ops_db.models.DataTransferLog` records
* For detailed data flow documentation, see the data-transfer documentation

system-integration
^^^^^^^^^^^^^^^^^^

The system-integration repository contains deployment configurations for ops-db and related
components:

* Docker Compose configurations
* Kubernetes manifests
* Ansible playbooks
* CI/CD pipelines

**Documentation:** :doc:`/system-integration/docs/index`

**Note:** For database deployment and infrastructure setup, see system-integration
documentation. This documentation (ops-db) covers only the database schema and Python API.

Using ops-db Programmatically
-----------------------------

If you're building a new component that needs to interact with ops-db:

Direct Python Access (recommended for Python applications)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Install ops-db as a Python package::

   pip install -e /path/to/ops-db

Then use the ORM directly::

   from ccat_ops_db import init_ccat_ops_db
   from ccat_ops_db.models import ObsUnit, ExecutedObsUnit

   session, engine = init_ccat_ops_db()
   obs_unit = session.query(ObsUnit).filter_by(name="my_obs").first()

See :doc:`../api_reference/core` for connection details and
:doc:`../api_reference/models` for model reference.

RESTful API Access (recommended for non-Python applications)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the ops-db-api for language-agnostic access::

   GET /api/v1/obs_units
   GET /api/v1/executed_obs_units/{id}
   POST /api/v1/raw_data_packages

See the ops-db-api documentation for endpoint details.

Direct SQL Access (not recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can connect directly to PostgreSQL, but you'll miss the benefits of:

* SQLAlchemy ORM (relationships, validation)
* Type checking (enums, polymorphic models)
* Business logic in model methods

If you must use direct SQL, refer to :doc:`../schema/database_layout` for schema details.

Related Documentation
----------------------

* Core functions: :doc:`../api_reference/core`
* Models API: :doc:`../api_reference/models`
* Database concepts: :doc:`../concepts/overview`