SSPACEAGEDOCUMENTATION/
Music and Workflow

SpaceAge Workflow Architecture Pass

Updated Aug 27, 2026   |   12.6 KB   |   docs/Spaceage_Workflow_Architecture_Pass.md

SpaceAge Workflow Architecture Pass

This document captures the current architectural direction for SpaceAge as the app moves from a collection of successful workstations into a coherent microDAW / groovebox environment.

North Star

SpaceAge should feel like a focused musical instrument first and a DAW second. It should let a user write drums, chords, bass, melody, SoundFont parts, physical-model parts, and later hardware/VST parts without learning a pile of unrelated workflows.

The target experience is:

  • Start quickly.
  • Choose or make sounds quickly.
  • Compose in specialized editors.
  • Arrange those ideas in lanes.
  • Mix each lane predictably.
  • Export audio, MIDI, stems, and portable archives without hidden surprises.

Core Architectural Invariants

These are rules we should protect unless there is a very strong reason to change them.

1. Arrangement Canvas Owns Song Time

The Arrangement Canvas is the master view of song time. Sequencers edit musical material, but the Arrangement Canvas decides when clips happen together.

This means:

  • Arranger playback should follow lanes, clips, loop range, playhead, mute/solo, and the global transport.
  • Piano Roll and Drum Composer can edit a selected clip, but when opened from the Arranger they should be able to hear the arrangement context unless the user solos/isolate-mutes lanes.
  • Rewind/fast-forward should not silently jump to unrelated pattern state. It should operate on the active timeline context.
  • The Arranger should support both detailed lane editing and a collapsed Overview Mode. Overview Mode is a song-map state for seeing many lanes at once; it should not pretend every detailed lane control can fit into that density.

2. One Lane Owns One Primary Instrument

Normal lanes should own one instrument target, one mixer channel strip, one MIDI input/output routing identity, and one musical role.

This gives us:

  • Predictable stem export.
  • Predictable mixer routing.
  • Predictable MIDI hardware routing.
  • Clean VST hosting later.
  • Better user trust: a clip cannot secretly contain a whole band.

Future exception: a special Polytimbral Lane can exist for General MIDI, XG hardware, multitimbral VSTs, or deliberate multi-channel hardware use. That should be a clearly labeled advanced lane type, not the default behavior.

3. Pads Should Stop Being The Melodic Instrument Registry

Pads remain excellent for drums, hybrid pads, sample layers, one-shots, and finger-drumming workflows.

But melodic lanes should target the Instrument Bay and lane-owned Instrument model:

  • Redshift / Moondagger / physical model / Kick Lab / SoundFont / future VST / future hardware profile.
  • Each instrument instance has its own patch state.
  • Each instrument instance owns or points to one mixer channel strip.
  • Each instrument instance can be renamed and saved independently.

This removes the current awkwardness where a melodic lane is indirectly tied to a pad slot.

4. Clips Need Clean Identity Rules

SpaceAge needs to be strict about the difference between clip instance and musical content.

Recommended model:

  • Clip Instance: lives on the Arrangement Canvas, has lane, start, length, selection state, notes, notes metadata, notes display, and clip notes.
  • Pattern / Payload: the actual musical data, such as Drum Composer steps, Piano Roll notes, Chord Markers, automation, and future Motion Blocks.
  • Linked Clone: another clip instance pointing to the same payload. Editing either changes both.
  • Variant: a copied payload with a new identity. Editing either no longer changes the other.

The important trap: if a user shortens a linked clip from 16 to 8 steps, the app must be clear whether that is trimming the instance length, changing the shared payload length, or creating a new variant. Silent ambiguity here creates almost every Arranger bug we have fought.

Near-term conservative rule:

  • Editing notes/chords changes the payload.
  • Resizing a clip in the Arranger changes the clip instance length.
  • Variant copies the current audible/visible contents into a new payload whose native length matches the clip's current length.
  • Clone copies the instance and preserves its linked relationship.

5. Lane Type And Clip Type Must Agree

A drum clip belongs in a drum-compatible lane. A melodic clip belongs in a melodic-compatible lane. A future audio clip belongs in an audio-compatible lane.

Do not silently allow foreign-lane dragging. The future conversion dialog should ask plain-language questions:

  • Convert this clip for the new lane?
  • Copy notes where possible?
  • Create a new compatible variant?
  • Cancel?

Until that exists, block foreign-lane drops.

6. One Command System For Undo

Undo should not be a patchwork. Any operation that changes musical state should eventually be represented as a command:

  • Add/remove/resize/move clip.
  • Add/remove/resize/move Section Marker.
  • Add/remove/resize notes.
  • Add/remove/resize Chord Markers.
  • Change lane instrument.
  • Change patch/preset.
  • Change mixer gain/send/mute/solo.
  • Clear notes.
  • Make Variant.
  • Paste.

This is not glamorous work, but it is what makes an app feel trustworthy.

7. One Timing Vocabulary

Snap, cut subdivision, loop length, arpeggiator rate, vibrato sync, LFO sync, delay sync, Motion Blocks, and future automation lanes should all speak one timing language.

Recommended shared vocabulary:

  • Free
  • Step
  • 1/2 step
  • 1/4 step
  • 1/8 step
  • Beat
  • 1/2 beat
  • 1/4 beat
  • Bar
  • 2 bars
  • 4 bars
  • Triplet variants where musically useful

This should be one reusable timing utility, not separate hardcoded lists for every panel.

8. Theory Data Needs One Source Of Truth

Scales, chord spellings, borrowed chords, chord detection, chord suggestions, Piano Roll key labels, MIDI import chord detection, and future score export must all share one theory layer.

If a scale spelling is fixed in one place but not another, users who know theory will notice immediately.

The theory engine should own:

  • Key signature / root / mode.
  • Scale spelling.
  • Enharmonic preference.
  • Chord formulas.
  • Slash-bass inversion labels.
  • Borrowed-chord source tags.
  • Chord detection labels.
  • Safe/color/tension/spare classifications.

9. Effects And Modulation Need Shared Routing

SpaceAge is starting to grow several movement systems:

  • Vibrato sync.
  • LFOs.
  • Arpeggiator.
  • Delay/reverb/chorus/flanger/phaser/tremolo sends.
  • Future Motion Blocks.
  • Future automation.

These should not become unrelated one-offs. Long-term, they should share a TempoAwareModulation layer:

  • Free rate or synced note value.
  • Depth.
  • Phase/start behavior.
  • Target.
  • Bypass/sleep behavior.

This lets us put tempo-sync dropdowns inside rotary controls later without reinventing sync math every time.

Workflow Priorities

Immediate Priority 1: Stabilize Lane-Owned Instrument Workflow

The user should understand, at a glance:

  • What lane is selected.
  • What instrument the lane owns.
  • What preset is active.
  • What mixer channel receives that lane.
  • Which lane is armed for MIDI input.
  • Whether the lane is muted or soloed.

Near-term work:

  • Improve lane header readability.
  • Make lane instrument/preset dropdowns wide enough and responsive.
  • Ensure lane instrument changes are saved/recalled.
  • Add clear warnings when changing a lane instrument with existing clips.
  • Make new lanes create a usable starter clip and instrument without hiding state in Pads.

Immediate Priority 2: SoundFont As A Serious Lane Instrument

SoundFonts are not a toy feature. They are a bridge to workstation-style composition and immediate musical testing.

SoundFont should behave like a real instrument:

  • Load/repair .sf2 path.
  • Select bank/program/preset clearly.
  • Save project state.
  • Archive safely.
  • Expose only meaningful patch controls.
  • Avoid duplicating mixer controls inside the patch page.
  • Support lane-owned MIDI channel/program thinking. First-pass lane MIDI channels now exist; future work should add device/port, bank/program, and hardware profiles without breaking that lane-owned model.

Important caution: SoundFont files differ wildly. Some controls may be subtle or patch-dependent. The UI must not imply a control is broken when the source material simply does not respond dramatically.

Immediate Priority 3: Chord Engine + Piano Roll As A Composer Surface

The Chord Engine is a differentiator. It should keep moving toward being the app's songwriting brain.

Near-term work:

  • Chord Markers should behave like notes wherever possible.
  • Honeycomb suggestions need consistent color, hover spelling, audition/commit behavior later, and stronger borrowed-chord language.
  • Chord audio should be clear: Chord + Arp, Arp Only, Reference Only.
  • Copy/paste chord progressions across clips.
  • Render chords/arps to editable notes.
  • Eventually detect chords from imported MIDI.

Immediate Priority 4: Drag/Snap Feel

The app's commercial polish depends heavily on how objects feel under the mouse.

Shared drag rules:

  • Object visually sticks to cursor.
  • Snap preview appears before drop.
  • Drop result is deterministic.
  • Existing content shifts only when the operation explicitly implies insertion.
  • Empty gaps are replaced when appropriate, not stacked behind real clips.
  • Escape cancels selection or active drag.

This applies to Arrangement clips, Section Markers, loop ranges, playheads, Piano Roll notes, Chord Markers, and eventually automation/Motion Blocks.

Architecture Debt Register

These are the areas most likely to punish us later if left fuzzy.

Pattern Length Versus Clip Length

This has already caused bugs. We need one clear rule and UI language.

Recommended wording:

  • Clip Length: how much timeline space this Arrangement clip occupies.
  • Pattern Length: how long the underlying musical pattern/payload is.

When they differ, the app must decide whether to loop, trim, leave silence, or create a variant. Do not guess silently.

Pad-Backed Melodic Instruments

This is workable now but should not be the final architecture. It limits lane counts, confuses SoundFont workflows, and makes pads feel like a hidden instrument rack.

Mixer Channel Ownership

Every lane-owned instrument should have one predictable mixer destination. Users should be able to reassign channels deliberately, but not accidentally create routing ambiguity.

SoundFont Preset State

Large General MIDI SoundFonts make SpaceAge feel like a workstation, but they introduce bank/program/state complexity. The project must save enough info to recall the same patch even if displayed names change or files move.

Theory Correctness

Chord and scale correctness is a product-quality issue, not academic trivia. Music-theory-aware users will trust or distrust SpaceAge based on spelling, inversion labels, and harmonic behavior.

Tempo Sync Lists

Vibrato sync, delay sync, LFO sync, arp rate, chop subdivisions, and Motion Blocks should all be driven by a shared list/model. Avoid one-off synced menus.

Pass 1: Lane Instrument And Mixer Coherence

Goal: make lanes feel like true tracks.

  • Widen/readability polish for lane instrument/preset controls.
  • Clear lane instrument selection workflow.
  • Save/reload lane instrument state audit.
  • MIDI input lane clarity.
  • Mixer channel ownership audit.
  • Fix any remaining cases where switching views/banks mutates channel state.

Pass 2: Chord Engine Composer Tools

Goal: make the Chord Engine feel world-class enough to justify the app's identity.

  • Consistent honeycomb colors and dismissal.
  • Better hover chord spellings.
  • Audition/commit mode.
  • Copy/paste chord progressions.
  • Borrow-from-key UI.
  • Render chord/arp to notes without losing original Chord Marker memory.

Pass 3: SoundFont Workstation Layer

Goal: make SoundFonts useful enough for full-song testing.

  • Better preset selector readability.
  • Patch metadata and repair path UI.
  • Meaningful SoundFont controls only.
  • Optional GM/XG-aware workflows later.
  • First-pass MIDI channel/program thinking per lane.

Definition Of Done For This Architecture Phase

This phase is healthy when:

  • A new user can create lanes, assign instruments, write clips, and arrange a small song without understanding Pads as hidden instrument storage.
  • A returning user can open a project and immediately see the song form, lane instruments, loop, playhead, and mix status.
  • Chord Engine, Piano Roll, Drum Composer, and Arranger share shortcuts and object behavior.
  • Copy/paste, clone, variant, delete, resize, and snap feel predictable.
  • Save/load/archive preserve sound sources, lanes, clips, chords, mixer state, and missing asset repair.
  • CPU stays disciplined: expensive effects/instruments sleep when not used.