# chai-student/crk-model architecture

> Architecture diagram of the GitHub repository chai-student/crk-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chai-student/crk-model
- Repository: https://github.com/chai-student/crk-model

## Overview

1. **What this repo is**
   - A legacy/reference **FastAPI model service** for an AI smart vending machine stack.
   - It is designed to run on a **Jetson Orin Nano 4GB** with **TensorRT `.engine`** inference.
   - The repo is the direct Python runtime path; the README notes a newer Go-based service exists elsewhere for fresh deployments.

2. **Process boundary and startup**
   - The process starts at `services/model/model_service/main.py`.
   - `api/manager.py` builds the FastAPI app and handles lifespan/bootstrap concerns.
   - `core/config.py` loads `.env`-based runtime settings into `app.state.settings`, which is now the central configuration boundary.

3. **HTTP/API surface**
   - `api/routes/health.py` exposes health endpoints for liveness/readiness and runtime diagnostics.
   - `api/routes/trigger.py` is the main ingest path for camera-triggered work.
   - `api/routes/multi_zone.py` exposes judgment/summary endpoints for multi-zone evaluation.
   - The route layer is thin; it delegates almost all work to services.

4. **Primary data flow: trigger to judgment**
   - The camera system sends an **AVI path** or trigger payload into `/trigger`.
   - The service does **not** infer directly on the AVI blob; it **splits AVI into frames**, runs inference per frame, and aggregates results.
   - Trigger handling is orchestrated by `service/trigger_service.py`, which coordinates video processing, vision inference, and session updates.

5. **Video ingestion and frame-level inference**
   - `video/video_processor.py`, `frame_extractor.py`, and `frame_trace.py` form the video processing boundary.
   - The model service works at **image-frame granularity** after frame extraction.
   - `camera_roles.py` and `freezer_candidate_policy.py` suggest the service distinguishes camera roles and selects candidate frames intelligently.
   - `voting_ensemble.py` indicates per-frame predictions are combined before producing a final decision.

6. **Vision/inference subsystem**
   - `vision/yolo_wrapper.py` is the model adapter around YOLO/TensorRT execution.
   - Supporting modules such as `top5_extractor.py`, `hand_filter.py`, and `hand_path_tracker.py` refine raw detections into usable product signals.
   - The model path is configured via settings and defaults to `models/0204_morning.engine` per the README.
   - This is the main dependency on Jetson CUDA/TensorRT runtime availability.

7. **Decision and weight logic**
   - `engine/decision_engine.py` and `engine/models.py` represent the higher-level business decision layer.
   - `weight/count_calculator.py` and `weight/strict_weight_matcher.py` handle loadcell-to-product matching logic.
   - The README notes the system sums **two physical loadcell channels per vending zone**, so weight math is zone-total based, not averaged.
   - This layer turns detection outputs plus weight signals into final judgments.

8. **Session and persistence boundaries**
   - `session/door_session.py`, `door_session_store.py`, `global_door_session.py`, and `session_store.py` manage active and completed evaluation sessions.
   - `session/product_aggregator.py`, `active_product_store.py`, and `freezer_close_aggregate.py` hold interim product evidence during a session.
   - `yaml_persistence.py` writes completed session artifacts under `services/model/model_service/data/sessions/...`.
   - This is the repo’s durable state boundary; runtime evaluation is session-centric rather than stateless.

9. **Operational tracing and observability**
   - `video/frame_trace.py` records frame-split and inference tracing.
   - The README notes persistent trace files under `services/model/logs/frame_split_*.jsonl`, plus optional sample frame export.
   - Logging setup and terminal handling live in `core/logging_config.py` and `core/terminal.py`.
   - This repo emphasizes post-run traceability because Jetson runtime behavior is only fully authoritative on-device.

10. **Runtime, environment, and platform coupling**
   - `core/runtime_env.py` and `core/model_validation.py` guard Jetson-specific runtime assumptions.
   - The service depends materially on **FastAPI**, **Uvicorn**, **NumPy**, **Ultralytics**, **Torch/CUDA**, and **TensorRT**.
   - `scripts/` contains Jetson setup, model conversion, and preview utilities, reinforcing that deployment and validation are tightly coupled to the device environment.
   - The repo is explicitly sensitive to Jetson package selection and CUDA/TensorRT availability.

11. **External systems and hardware interfaces**
   - Primary external inputs are the **camera feed/AVI files** and **loadcell signals** coming from the vending hardware stack.
   - The docs tree references protocol contracts for **camera**, **I/O board**, **node**, and **payment**, indicating this model service sits in a larger device ecosystem even though the code here mainly consumes camera and weight data.
   - The service’s outputs are decisions/judgments consumed by the rest of the vending-machine control system.

12. **Testing and verification boundary**
   - `services/model/tests/` contains unit and contract tests for the API, decision engine, session store, trigger pipeline, weight matching, and YOLO geometry.
   - The README stresses that local tests validate imports and logic, but **Jetson runtime checks are authoritative** for camera decoding, TensorRT loading, and trigger behavior.
   - That means the architecture has a clear split between **host-side correctness** and **device-side operational readiness**.

13. **How to draw the architecture**
   - Model the service as a pipeline with four main layers:
     1. **HTTP/API ingress**
     2. **Trigger orchestration and session management**
     3. **Frame extraction + YOLO/vision inference**
     4. **Decision/weight aggregation + persistence**
   - Put Jetson CUDA/TensorRT and camera/loadcell hardware outside the service boundary as runtime dependencies.
   - Put YAML session artifacts and JSONL frame traces as durable outputs on the storage side.

Main entry points: [`services/model/model_service/api/manager.py`](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/manager.py) (App Manager), [`services/model/model_service/service/trigger_service.py`](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/trigger_service.py) (Trigger Service), [`services/model/model_service/video/video_processor.py`](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/video_processor.py) (Video Processor), [`services/model/model_service/engine/decision_engine.py`](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/engine/decision_engine.py) (Decision Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_api["API Boundary"]
  node_n_main(("Entrypoint<br/>process bootstrap<br/>[main.py]"))
  node_n_manager["App Manager<br/>FastAPI app<br/>[manager.py]"]
  node_n_health["Health Routes<br/>http routes<br/>[health.py]"]
  node_n_trigger_route["Trigger Routes<br/>http routes<br/>[trigger.py]"]
  node_n_multi_zone_route["Multi-zone Routes<br/>http routes<br/>[multi_zone.py]"]
end

subgraph group_grp_core["Core Runtime"]
  node_n_config["Settings<br/>runtime config<br/>[config.py]"]
  node_n_runtime_env["Runtime Env<br/>jetson guard<br/>[runtime_env.py]"]
  node_n_model_validation["Model Validation<br/>startup checks"]
  node_n_logging["Logging<br/>[logging_config.py]"]
end

subgraph group_grp_trigger["Trigger Pipeline"]
  node_n_trigger_service["Trigger Service<br/>orchestration service<br/>[trigger_service.py]"]
  node_n_judgment_service["Judgment Service<br/>application service"]
end

subgraph group_grp_video["Video + Vision"]
  node_n_video_processor["Video Processor<br/>video pipeline<br/>[video_processor.py]"]
  node_n_frame_extractor["Frame Extractor<br/>frame ingestion<br/>[frame_extractor.py]"]
  node_n_frame_trace["Frame Trace<br/>observability<br/>[frame_trace.py]"]
  node_n_voting["Voting Ensemble<br/>aggregation<br/>[voting_ensemble.py]"]
  node_n_yolo["YOLO Wrapper<br/>tensorrt adapter<br/>[yolo_wrapper.py]"]
  node_n_vision_filters["Vision Filters<br/>post-processing<br/>[hand_filter.py]"]
  node_n_top5["Top-5 Extractor<br/>ranker<br/>[top5_extractor.py]"]
end

subgraph group_grp_session["Session State"]
  node_n_door_session_service["Door Session<br/>session service"]
  node_n_session_store[("Session Store<br/>session persistence<br/>[session_store.py]")]
  node_n_door_store[("Door Store<br/>session store")]
  node_n_global_session(("Global Session<br/>session state"))
  node_n_product_agg["Product Aggregator<br/>evidence aggregation"]
  node_n_yaml_persist["YAML Persistence<br/>artifact writer"]
end

subgraph group_grp_decision["Decision Logic"]
  node_n_weight_logic["Weight Logic<br/>loadcell matching"]
  node_n_strict_matcher["Strict Matcher<br/>matching rule"]
  node_n_decision_engine["Decision Engine<br/>business rules<br/>[decision_engine.py]"]
end

node_n_main -->|"boot"| node_n_manager
node_n_manager -->|"loads"| node_n_config
node_n_manager -->|"configures"| node_n_logging
node_n_manager -->|"guards"| node_n_runtime_env
node_n_manager -->|"validates"| node_n_model_validation
node_n_manager -->|"mounts"| node_n_health
node_n_manager -->|"mounts"| node_n_trigger_route
node_n_manager -->|"mounts"| node_n_multi_zone_route
node_n_trigger_route -->|"delegates"| node_n_trigger_service
node_n_multi_zone_route -->|"delegates"| node_n_judgment_service
node_n_trigger_service -->|"orchestrates"| node_n_video_processor
node_n_trigger_service -->|"updates"| node_n_door_session_service
node_n_trigger_service -->|"evaluates"| node_n_decision_engine
node_n_video_processor -->|"splits"| node_n_frame_extractor
node_n_video_processor -->|"traces"| node_n_frame_trace
node_n_video_processor -->|"infers"| node_n_yolo
node_n_yolo -->|"refines"| node_n_vision_filters
node_n_vision_filters -->|"ranks"| node_n_top5
node_n_video_processor -->|"aggregates"| node_n_voting
node_n_decision_engine -->|"combines"| node_n_weight_logic
node_n_weight_logic -->|"matches"| node_n_strict_matcher
node_n_decision_engine -->|"uses"| node_n_product_agg
node_n_product_agg -->|"stores"| node_n_session_store
node_n_door_session_service -->|"persists"| node_n_door_store
node_n_door_session_service -->|"shares"| node_n_global_session
node_n_session_store -->|"writes"| node_n_yaml_persist
node_n_trigger_service -->|"reads/writes"| node_n_session_store
node_n_judgment_service -->|"evaluates"| node_n_decision_engine
node_n_judgment_service -->|"archives"| node_n_yaml_persist

click node_n_main "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/main.py"
click node_n_manager "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/manager.py"
click node_n_health "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/routes/health.py"
click node_n_trigger_route "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/routes/trigger.py"
click node_n_multi_zone_route "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/routes/multi_zone.py"
click node_n_config "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/config.py"
click node_n_runtime_env "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/runtime_env.py"
click node_n_model_validation "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/model_validation.py"
click node_n_logging "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/logging_config.py"
click node_n_trigger_service "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/trigger_service.py"
click node_n_judgment_service "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/judgment_service.py"
click node_n_door_session_service "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/door_session_service.py"
click node_n_video_processor "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/video_processor.py"
click node_n_frame_extractor "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/frame_extractor.py"
click node_n_frame_trace "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/frame_trace.py"
click node_n_voting "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/voting_ensemble.py"
click node_n_yolo "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/vision/yolo_wrapper.py"
click node_n_vision_filters "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/vision/hand_filter.py"
click node_n_top5 "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/vision/top5_extractor.py"
click node_n_weight_logic "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/weight/count_calculator.py"
click node_n_strict_matcher "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/weight/strict_weight_matcher.py"
click node_n_decision_engine "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/engine/decision_engine.py"
click node_n_session_store "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/session_store.py"
click node_n_door_store "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/door_session_store.py"
click node_n_global_session "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/global_door_session.py"
click node_n_product_agg "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/product_aggregator.py"
click node_n_yaml_persist "https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/yaml_persistence.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main,node_n_manager,node_n_health,node_n_trigger_route,node_n_multi_zone_route toneBlue
class node_n_config,node_n_runtime_env,node_n_model_validation,node_n_logging toneAmber
class node_n_trigger_service,node_n_judgment_service toneMint
class node_n_video_processor,node_n_frame_extractor,node_n_frame_trace,node_n_voting,node_n_yolo,node_n_vision_filters,node_n_top5 toneRose
class node_n_door_session_service,node_n_session_store,node_n_door_store,node_n_global_session,node_n_product_agg,node_n_yaml_persist toneIndigo
class node_n_weight_logic,node_n_strict_matcher,node_n_decision_engine toneTeal
```

## Components

### API Boundary

FastAPI startup and HTTP routes

- [Entrypoint](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/main.py): process bootstrap · Starts the model service process and hands off to the app manager. · `services/model/model_service/main.py`
- [App Manager](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/manager.py): FastAPI app · Builds the FastAPI application and manages lifespan/bootstrap. · `services/model/model_service/api/manager.py`
- [Health Routes](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/routes/health.py): http routes · Liveness, readiness, and runtime diagnostics endpoints. · `services/model/model_service/api/routes/health.py`
- [Trigger Routes](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/routes/trigger.py): http routes · Main ingest surface for camera-triggered work. · `services/model/model_service/api/routes/trigger.py`
- [Multi-zone Routes](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/api/routes/multi_zone.py): http routes · Judgment and summary endpoints for multi-zone evaluation. · `services/model/model_service/api/routes/multi_zone.py`

### Core Runtime

Settings, logging, validation, and startup support

- [Settings](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/config.py): runtime config · Loads env-based runtime settings into application state. · `services/model/model_service/core/config.py`
- [Runtime Env](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/runtime_env.py): jetson guard · Checks device/runtime assumptions for the Jetson deployment. · `services/model/model_service/core/runtime_env.py`
- [Model Validation](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/model_validation.py): startup checks · Validates model/runtime readiness before inference use. · `services/model/model_service/core/model_validation.py`
- [Logging](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/core/logging_config.py): runtime logging · Configures service logging and trace-friendly output. · `services/model/model_service/core/logging_config.py`

### Trigger Pipeline

Orchestrates camera-triggered processing and judgments

- [Trigger Service](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/trigger_service.py): orchestration service · Coordinates AVI/frame processing, inference, and session updates. · `services/model/model_service/service/trigger_service.py`
- [Judgment Service](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/judgment_service.py): application service · Produces the final judgment from aggregated evidence. · `services/model/model_service/service/judgment_service.py`

### Video + Vision

Frame extraction and TensorRT/YOLO inference

- [Video Processor](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/video_processor.py): video pipeline · Splits AVI input into frames and drives frame-level processing. · `services/model/model_service/video/video_processor.py`
- [Frame Extractor](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/frame_extractor.py): frame ingestion · Extracts usable frames from video input. · `services/model/model_service/video/frame_extractor.py`
- [Frame Trace](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/frame_trace.py): observability · Records split and inference trace artifacts for post-run analysis. · `services/model/model_service/video/frame_trace.py`
- [Voting Ensemble](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/video/voting_ensemble.py): aggregation · Combines per-frame predictions into a final result. · `services/model/model_service/video/voting_ensemble.py`
- [YOLO Wrapper](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/vision/yolo_wrapper.py): tensorrt adapter · Wraps YOLO/TensorRT execution for vision inference. · `services/model/model_service/vision/yolo_wrapper.py`
- [Vision Filters](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/vision/hand_filter.py): post-processing · Refines detections into product signals and tracks hands. · `services/model/model_service/vision/hand_filter.py`
- [Top-5 Extractor](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/vision/top5_extractor.py): ranker · Extracts ranked product candidates from detections. · `services/model/model_service/vision/top5_extractor.py`

### Session State

Active evaluation state and persistence

- [Door Session](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/service/door_session_service.py): session service · Manages session lifecycle and door-scoped evaluation state. · `services/model/model_service/service/door_session_service.py`
- [Session Store](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/session_store.py): session persistence · Stores active and completed session state. · `services/model/model_service/session/session_store.py`
- [Door Store](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/door_session_store.py): session store · Keeps door-scoped session records and transitions. · `services/model/model_service/session/door_session_store.py`
- [Global Session](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/global_door_session.py): session state · Holds cross-session state for active evaluations. · `services/model/model_service/session/global_door_session.py`
- [Product Aggregator](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/product_aggregator.py): evidence aggregation · Accumulates interim product evidence during a session. · `services/model/model_service/session/product_aggregator.py`
- [YAML Persistence](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/session/yaml_persistence.py): artifact writer · Writes completed session artifacts to disk. · `services/model/model_service/session/yaml_persistence.py`

### Decision Logic

Weight matching and final business decisions

- [Weight Logic](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/weight/count_calculator.py): loadcell matching · Matches loadcell totals to product evidence. · `services/model/model_service/weight/count_calculator.py`
- [Strict Matcher](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/weight/strict_weight_matcher.py): matching rule · Applies strict weight-to-product matching rules. · `services/model/model_service/weight/strict_weight_matcher.py`
- [Decision Engine](https://github.com/chai-student/crk-model/blob/main/services/model/model_service/engine/decision_engine.py): business rules · Turns detections and weight signals into final decisions. · `services/model/model_service/engine/decision_engine.py`

## Connections

- Entrypoint → App Manager: boot · Process entry loads the FastAPI app manager.
- App Manager → Settings: loads · Bootstrap resolves runtime settings into app state.
- App Manager → Logging: configures · App startup configures logging and terminal behavior.
- App Manager → Runtime Env: guards · Startup checks Jetson/runtime assumptions.
- App Manager → Model Validation: validates · Startup validates model and runtime readiness.
- App Manager → Health Routes: mounts · Registers health and diagnostics routes.
- App Manager → Trigger Routes: mounts · Registers the main trigger ingest route.
- App Manager → Multi-zone Routes: mounts · Registers multi-zone judgment and summary routes.
- Trigger Routes → Trigger Service: delegates · HTTP ingest hands off to trigger orchestration.
- Multi-zone Routes → Judgment Service: delegates · Summary endpoints delegate to judgment logic.
- Trigger Service → Video Processor: orchestrates · Trigger handling starts video-to-frame processing.
- Trigger Service → Door Session: updates · Trigger flow updates session lifecycle state.
- Trigger Service → Decision Engine: evaluates · Trigger flow produces final decisions through the engine.
- Video Processor → Frame Extractor: splits · Video input is decomposed into frames.
- Video Processor → Frame Trace: traces · Frame splitting and inference are recorded for observability.
- Video Processor → YOLO Wrapper: infers · Frames are sent to the TensorRT-backed detector.
- YOLO Wrapper → Vision Filters: refines · Raw detections are filtered into usable signals.
- Vision Filters → Top-5 Extractor: ranks · Filtered detections feed product ranking.
- Video Processor → Voting Ensemble: aggregates · Per-frame outputs are combined into a final video result.
- Decision Engine → Weight Logic: combines · Decision logic consumes loadcell-derived product matching.
- Weight Logic → Strict Matcher: matches · Weight totals are matched to product candidates.
- Decision Engine → Product Aggregator: uses · Business decisions draw on accumulated product evidence.
- Product Aggregator → Session Store: stores · Product evidence is kept in session state.
- Door Session → Door Store: persists · Door-scoped sessions are stored and retrieved.
- Door Session → Global Session: shares · Session service coordinates cross-session state.
- Session Store → YAML Persistence: writes · Completed sessions are serialized as YAML artifacts.
- Trigger Service → Session Store: reads/writes · Trigger orchestration updates the active session boundary.
- Judgment Service → Decision Engine: evaluates · Judgment generation depends on the decision engine.
- Judgment Service → YAML Persistence: archives · Final judgments are captured in durable session output.
