# Project Principles

Version: 1.0

This document defines the core engineering philosophy of AI MusiMuse.

Unlike **SPEC.md**, this document is intentionally short.

These principles should guide every architectural decision, every code review and every implementation task.

If any principle conflicts with **SPEC.md**, the specification takes priority.

---

# 1. Understand Before Generate

Understanding music is the primary objective.

Generation is only the consequence of understanding.

---

# 2. Architecture Before Code

Good architecture produces good code.

Never sacrifice architecture for short-term convenience.

---

# 3. Simplicity Wins

Choose the simplest solution that correctly solves the problem.

Complexity must always justify its existence.

---

# 4. Everything is Measured

Assumptions are temporary.

Measurements are permanent.

Whenever possible, replace opinions with measurable observations.

---

# 5. Explain Every Decision

If a result cannot be explained, it cannot be trusted.

Every important conclusion should expose the evidence that produced it.

---

# 6. Determinism First

Identical inputs must produce identical outputs.

Randomness must always be explicit, configurable and documented.

---

# 7. Version Everything

Algorithms evolve.

Knowledge evolves.

Data evolves.

Never overwrite history.

Every important artifact should have a version.

---

# 8. Small Independent Modules

A module should have one responsibility.

A module should be understandable without reading the entire project.

Small modules are easier to test, maintain and replace.

---

# 9. Prefer Composition

Favor composition over inheritance.

Prefer explicit dependencies over hidden behavior.

Avoid unnecessary abstraction.

---

# 10. Human Readability Matters

Code is read far more often than it is written.

Write for the next engineer, not for the compiler.

---

# 11. The Database Stores Knowledge

The database is the long-term memory of the system.

It stores facts, not implementation details.

Algorithms may change.

Knowledge should remain reproducible.

---

# 12. Offline by Default

Core functionality must never depend on Internet access.

Cloud services are optional extensions.

---

# 13. Every Layer Has One Job

Scanner discovers files.

Decoder reads audio.

DSP measures signals.

Music DNA interprets measurements.

Embeddings represent music.

Similarity compares works.

Recommendations inspire creativity.

No layer should perform the responsibility of another.

---

# 14. Build for the Next Ten Years

Choose solutions that remain understandable and maintainable over time.

Avoid shortcuts that create future technical debt.

Long-term clarity is more valuable than short-term speed.

---

# 15. Research, Not Guesswork

AI MusiMuse is a research platform.

Engineering decisions should be supported by evidence whenever possible.

Experimentation is encouraged.

Uncontrolled complexity is not.

---

# Project Motto

Understand.

Measure.

Remember.

Reason.

Inspire.

Generation is only the consequence of understanding.