# Component: Domain Models & Configuration

## Overview

**Purpose**: Provides all data models, enums, constants, detection class registry, and logging infrastructure used across the system.

**Pattern**: Shared kernel — leaf-level types and utilities consumed by all other components.

**Upstream**: None (foundation layer).
**Downstream**: Inference Engines, Inference Pipeline, API.

## Modules

| Module | Role |
|--------|------|
| `constants_inf` | Application constants, logging, detection class registry from `classes.json` |
| `ai_config` | `AIRecognitionConfig` data class with factory methods |
| `ai_availability_status` | Thread-safe `AIAvailabilityStatus` tracker with `AIAvailabilityEnum` |
| `annotation` | `Detection` and `Annotation` data models |

## Internal Interfaces

### constants_inf

```
cdef log(str log_message) -> void
cdef logerror(str error) -> void
cdef format_time(int ms) -> str
annotations_dict: dict[int, AnnotationClass]
```

### ai_config

```
cdef class AIRecognitionConfig:
    @staticmethod cdef from_msgpack(bytes data) -> AIRecognitionConfig
    @staticmethod def from_dict(dict data) -> AIRecognitionConfig
```

### ai_availability_status

```
cdef class AIAvailabilityStatus:
    cdef set_status(AIAvailabilityEnum status, str error_message=None)
    cdef bytes serialize()
    # __str__ for display
```

### annotation

```
cdef class Detection:
    cdef overlaps(Detection det2, float confidence_threshold) -> bool
    # __eq__ for tile deduplication

cdef class Annotation:
    cdef bytes serialize()
```

## External API

None — this is a shared kernel, not an externally-facing component.

## Data Access Patterns

- `classes.json` read once at module import time (constants_inf)
- All data is in-memory, no database access

## Implementation Details

- Cython `cdef` classes for performance-critical detection processing
- Thread-safe status tracking via `threading.Lock` in `AIAvailabilityStatus`
- `Detection.__eq__` uses coordinate proximity threshold for tile deduplication
- `Detection.overlaps` uses containment-biased metric (overlap / min_area) rather than standard IoU
- Weather mode system triples the class registry (Norm/Wint/Night offsets of 0/20/40)

## Caveats

- `classes.json` must exist in the working directory at import time — no fallback
- `Detection.__eq__` is designed specifically for tile deduplication, not general equality
- `annotations_dict` is a module-level global — not injectable/configurable at runtime

## Dependency Graph

```mermaid
graph TD
    ai_availability_status --> constants_inf
    annotation --> constants_inf
    ai_config
    constants_inf
```

## Logging Strategy

All logging flows through `constants_inf.log` and `constants_inf.logerror`, which delegate to loguru with file rotation and console output.