112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
# 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.
|
|
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.
|
|
|
|
## 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.
|