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

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. For automatic decisions, the AI Director requests only enabled automatic scopes and merges the response into the current project while preserving manual structure, arrangement, musical-parameter and production choices. When a Song Project uses Discuss mode, the AI Director sends the current project and conversation context to the provider and returns follow-up questions without applying a project update.

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.

3.2 KiB Raw Blame History