00-overview
===========

.. py:module:: 00-overview

.. autoapi-nested-parse::

   Overview Diagram Generator
   --------------------------
   Generates the architecture overview (PNG & SVG) with brand icons when available.

   Outputs:
     docs/architecture/exports/00-overview.png
     docs/architecture/exports/00-overview.svg

   Icon search path:
     docs/architecture/icons/
     Expected names : kafka.svg, spark.svg, postgres.svg, dbt.svg, airflow.svg,
                      pandas.svg, datasource.svg, analyst.svg
     Missing icons gracefully fall back to built-in diagram nodes.

   Requirements (install locally):
     - Python 3.9+
     - Graphviz system package



Attributes
----------

.. autoapisummary::

   00-overview.BASE_DIR
   00-overview.ICONS_DIR
   00-overview.EXPORTS_DIR
   00-overview.PROCESSED_DIR
   00-overview.TITLE
   00-overview.DEFAULT_OUT_BASENAME
   00-overview.LBL_JDBC_UPSERT
   00-overview.LBL_SPARKSUBMIT
   00-overview.LBL_DBT_RUN
   00-overview.ICON_SIZE
   00-overview.ICON_BORDER
   00-overview.ICON_BORDER_ALPHA
   00-overview.ICON_BORDER_COLOR
   00-overview.ICON_INNER_MARGIN
   00-overview.ICON_NAMES


Functions
---------

.. autoapisummary::

   00-overview.graphviz_available
   00-overview.ensure_dirs
   00-overview._raw_icon_path
   00-overview._process_icon
   00-overview.icon
   00-overview._node
   00-overview.wire_edges
   00-overview.render
   00-overview.main


Module Contents
---------------

.. py:data:: BASE_DIR

.. py:data:: ICONS_DIR

.. py:data:: EXPORTS_DIR

.. py:data:: PROCESSED_DIR

.. py:data:: TITLE
   :value: 'Rides Analytics — Overview'


.. py:data:: DEFAULT_OUT_BASENAME
   :value: '00-overview'


.. py:data:: LBL_JDBC_UPSERT
   :value: 'JDBC upsert'


.. py:data:: LBL_SPARKSUBMIT
   :value: 'SparkSubmit (hourly)'


.. py:data:: LBL_DBT_RUN
   :value: 'dbt run + test'


.. py:data:: ICON_SIZE
   :value: 256


.. py:data:: ICON_BORDER
   :value: 6


.. py:data:: ICON_BORDER_ALPHA
   :value: 180


.. py:data:: ICON_BORDER_COLOR

.. py:data:: ICON_INNER_MARGIN
   :value: 12


.. py:data:: ICON_NAMES
   :value: ['kafka', 'spark', 'postgres', 'dbt', 'airflow', 'pandas', 'datasource', 'analyst']


.. py:function:: graphviz_available() -> bool

.. py:function:: ensure_dirs() -> None

.. py:function:: _raw_icon_path(name: str) -> Optional[pathlib.Path]

   Return the path to a raw source icon if it exists (PNG only, per current script).


.. py:function:: _process_icon(raw: pathlib.Path) -> pathlib.Path

   Normalize icon to a square PNG canvas with transparent background,
   add a border rectangle, and cache to PROCESSED_DIR.
   If Pillow isn't available, fall back to the raw icon.


.. py:function:: icon(name: str) -> Optional[pathlib.Path]

   Return a Path to a normalized, bordered icon (PNG) if available; else raw PNG; else None.


.. py:function:: _node(label: str, icon_name: str, fallback_cls)

.. py:function:: wire_edges(nodes: Dict[str, object]) -> None

   Wire edges according to the agreed overview spec.
   Top row (stream path): Source → Kafka → Spark Streaming → Postgres
   Bottom row (batch/orchestration): Airflow → Spark Batch → Postgres → dbt → Postgres → Analyst


.. py:function:: render(out_basename: str, formats: list[str]) -> None

   Render the diagram for all requested formats. Adds three rectangles (clusters):
     - App (outer)
     - Streaming Process (inner)
     - Batch & Orchestration (inner)


.. py:function:: main() -> None