Initial commit

2026-09-13 20:21:10 +02:00
commit 18d7d56345
42 changed files with 5459 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Architecture --- Initial Direction
+
+## Principle
+
+Keep UI, domain data, AI orchestration, external integrations and
+persistence separated. Do not hard-code provider behavior into SwiftUI
+views.
+
+## Suggested Layers
+
+``` text
+macOS App
+├── Presentation (SwiftUI)
+├── Domain
+│   ├── SongProject
+│   ├── SongVersion
+│   ├── Lyrics
+│   ├── SongStructure
+│   ├── Genre/Style
+│   ├── Instrument
+│   ├── Vocal
+│   ├── Arrangement
+│   └── MusicalParameters
+├── Application Services
+│   ├── AI Director
+│   ├── Prompt Compiler
+│   ├── Instrument Catalog
+│   ├── Arabic Pronunciation Processor
+│   ├── Project Versioning
+│   └── Validation
+├── Integrations
+│   ├── OpenAI
+│   └── Suno Field-Fill Integration
+└── Persistence
+    └── Local project/version storage
+```
+
+## AI Director
+
+OpenAI receives the user's intent plus private application rules and
+structured project state. AI output should be requested as structured
+data wherever possible, not treated as an unstructured chat transcript.
+
+## Prompt Compiler
+
+A deterministic layer converts the approved SongProject into the final
+Suno-facing lyrics/style content. User choices override AI suggestions.
+
+## Security
+
+-   Never commit API keys to source control.
+-   Keep secrets outside source code.
+-   Design provider clients behind protocols/interfaces so credentials
+    and providers can be changed later.
+-   Do not log secrets or full authorization headers.
+
+## Suno Boundary
+
+The initial requirement is browser/site handoff that fills fields but
+does not press Generate. Treat this integration as replaceable because
+website UI/behavior can change.
+
+## Instrument Selector Boundary
+
+Instrument catalog data is structured names and metadata, not SwiftUI
+view code. The Presentation layer may search, filter and toggle
+selections, but catalog loading, search normalization and selected
+instrument state should live in Domain/Application Services and the
+SongProject model.
+
+Catalog entries should include stable ids, display names,
+family/category, optional region/origin and optional aliases/search
+terms. The catalog should support worldwide coverage across Western,
+Middle Eastern, African, South Asian, East Asian, Southeast Asian, Latin
+American, traditional, folk, orchestral, electronic and modern
+instruments.
+
+Selected instruments are part of the SongProject and must be available
+to the AI Director and Prompt Compiler so they can influence
+arrangement, roles, entry/exit timing, relevant structure decisions and
+the Suno Style Prompt.
+
+The current architecture does not include instrument images, audio
+previews, sound samples, playback, Freesound, an Instrument API or
+external API calls for instrument data.