# AI MusiMuse Architecture

Version: 0.1.0-dev

This document summarizes the high-level architecture defined in `SPEC.md`.

## Overview

AI MusiMuse is an offline-first research platform for understanding a composer's musical identity. The system follows a layered pipeline where each module has a single responsibility and communicates through typed domain objects.

## Pipeline

```text
Music Library
      │
      ▼
File Scanner
      │
      ▼
Audio Decoder
      │
      ▼
DSP Engine
      │
      ▼
Music DNA Engine
      │
      ▼
Embedding Engine
      │
      ▼
Similarity Engine
      │
      ▼
Memory Database
      │
      ▼
Recommendation Engine
      │
      ▼
LLM Reasoner (future)
      │
      ▼
User Interface (future)
```

## Layer Rules

- Dependencies always point inward toward lower layers.
- Lower layers must never depend on upper layers.
- Only the LLM Reasoner may contain probabilistic reasoning.
- Everything before it must remain deterministic.

## Current Status (v0.1.0-dev)

TASK-001 provides project bootstrap only:

- Configuration via Pydantic Settings
- Structured logging via structlog
- SQLite engine and session factory via SQLAlchemy 2.0
- Placeholder packages for future modules

No analysis algorithms, database models, or business logic are implemented yet.

## Module Responsibilities

| Module | Responsibility |
|--------|----------------|
| `scanner` | Discover audio files and build track manifests |
| `decoder` | Load and normalize audio into buffers |
| `dsp` | Extract objective measurable features |
| `features` | Feature Definition Registry: canonical identifiers, metadata, and normalization |
| `music_dna` | Build MusicDNA from features and encode into float32 vectors |
| `embeddings` | Generate vector representations |
| `similarity` | Compare MusicDNAVectors with cosine, euclidean, manhattan metrics |
| `recommendations` | Produce evidence-backed creative suggestions |
| `reports` | Generate human-readable reports |
| `plugins` | Extend the system without modifying core code |
| `database` | Persist long-term musical knowledge |
| `config` | Runtime configuration |
| `log` | Reproducibility-oriented structured logs |

## Data Principles

- The database stores immutable facts.
- Algorithms evolve; historical results are never modified.
- Every stored value records what was measured, how, and by which algorithm version.

For the full specification, see `SPEC.md`.

---

# Future Evolution

The current architecture is intentionally minimal.

At this stage, every analyzer execution is independent and directly produces immutable features.

Current execution flow:

```
Track
   │
   ▼
AudioDecoder
   │
   ▼
DecodedAudio
   │
   ▼
AnalysisContext
   │
   ▼
AnalysisPipeline
   │
   ▼
AnalyzerRun
   │
   ▼
TrackFeature
```

This design keeps the system simple while the project is in its early development stages.

---

## Planned Evolution

As AI MusiMuse grows, a future version of the architecture may introduce an `AnalysisSession` entity.

An AnalysisSession will represent one complete execution of the analysis pipeline for a track.

Future architecture:

```
Track
   │
   ▼
AnalysisSession
   │
   ▼
AnalysisPipeline
   │
   ├── AnalyzerRun (Basic Signal)
   ├── AnalyzerRun (Spectral)
   ├── AnalyzerRun (Dynamics)
   ├── AnalyzerRun (Rhythm)
   ├── AnalyzerRun (Harmony)
   └── AnalyzerRun (Music DNA)
             │
             ▼
        TrackFeature
```

---

## Purpose of AnalysisSession

AnalysisSession is intentionally **not implemented yet**.

It is reserved for future capabilities such as:

- incremental analysis
- partial analyzer execution
- re-analysis after analyzer upgrades
- analysis history
- comparison between analysis runs
- parallel execution
- distributed processing
- job queue integration
- web interface support

Introducing AnalysisSession now would add unnecessary complexity without providing practical benefits.

The current architecture should therefore remain:

```
Track
    ↓
AnalyzerRun
    ↓
TrackFeature
```

until one of the above requirements becomes necessary.

The project follows the **YAGNI (You Aren't Gonna Need It)** principle: features are introduced only when they solve a real problem, while the architecture remains open for future extension.