4.5 KiB
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. All structured AI updates pass through a scope-aware merger. It applies only the scopes declared by the response, ignores user-locked scopes and preserves manual control values. AI provider calls can be wrapped by a configurable retry service. It retries only temporary network, server and rate-limit failures, honors a provider-supplied retry delay when available, and propagates cancellation without retrying.
Prompt Compiler
A deterministic layer converts the approved SongProject into the final Suno-facing lyrics/style content. User choices override AI suggestions. It depends only on approved domain data and local validation; it does not invoke the OpenAI client or reference SwiftUI presentation code.
Arabic Pronunciation Processor
The Arabic Pronunciation Processor is a local Application Service. It normalizes user-supplied Arabic diacritics and applies the selected tanween policy without choosing a diacritization policy for the user. It must not invent missing vowel marks or tanween when no reliable linguistic source is available; instead, it returns a review note so a later user-review flow can present the unresolved text. This processor does not use external services or APIs. Before processing, it protects the user's exact preserved spellings and dialect phrases so normalization or tanween removal cannot alter them. The Presentation layer presents both the original and processed lyrics in final review; the user may edit and explicitly apply the processed text before any Suno handoff.
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.