Tasks

Overview

This report reviews the current music-study architecture and proposes a safer path for expanding it into a long-term music theory study platform, especially for advanced material such as George Russell's Lydian Chromatic Concept and the class workflow around chord targets, parent scales, and improvisation.

The current app already has a good foundation: React + TypeScript + Vite, feature-oriented UI folders, a src/theory/ layer, shared music types, audio hooks, and a lightweight i18n layer. The next important step is not a redesign. It is to make the theoretical knowledge more modular, editable, and expandable without scattering text and music rules across UI components.

What is already working well

1. The app already separates UI, hooks, theory, audio, and types

The current project structure is close to the right direction:

src/
  audio/
  components/
  hooks/
  theory/
  types/
  i18n/

The top-level App.tsx is mostly orchestration. It wires the selected tonic, selected scales, tab state, audio actions, and feature sections together. This is a good pattern because the app shell does not directly compute the musical material.

2. The scale engine is already centralized

useScaleEngine.ts handles the main state:

tonic
selected scales
display mode
computed scale results
scale comparisons
localStorage persistence

This means new sections can reuse the same basic app state, especially the selected tonic.

3. The theory layer already has useful pure functions

The current src/theory/ layer contains:

scales.ts: definitions of the four parent scales currently supported
modes.ts: definitions of modes derived from those scales
chords.ts: harmonic field generation and chord quality detection
engine.ts: public functions such as computeScale, deriveModes, and compareScales
constants.ts: chromatic notes, enharmonic spellings, degree-to-semitone mapping, scale note tables, tonic selector data

This is the right place for theoretical derivation. Future features should keep this discipline.

4. The enharmonic tonic selector is a good UI solution

The app already has an elegant note selector where enharmonic pairs such as C# / Db are shown together but each side is clickable independently. This should be reused for the Lydian Chromatic section.

5. The i18n layer is already prepared for growth

The lightweight t(key) helper and locale files are useful. The next step is to avoid placing long pedagogical definitions inside theory data files or UI components. Instead, theoretical entities should have stable IDs, and the explanatory text should live in dictionary/locale files.

Main architecture issue

The current app centralizes some theory rules, but it still mixes four different kinds of information in the same files:

Musical computation rules
Static catalog data
Pedagogical explanation text
UI-facing labels and mood descriptions

Examples:

scales.ts contains scale formulas and also explanatory descriptions.
modes.ts contains modal formulas and also mood/copywriting descriptions.
chords.ts computes chord quality and also writes explanatory text.
engine.ts compares scales and also writes pedagogical explanations.

This works for a small app, but it becomes risky when adding advanced concepts. The Lydian Chromatic Concept should not simply be pasted into the existing scale/mode structure because it is not just another parent scale list. It introduces a different workflow: chord type → target/alvo → parent scale → ordered scale choices → melodic application.

Recommended direction

Create a clearer separation between:

src/theory/core/
  notes.ts
  intervals.ts
  degrees.ts
  enharmonics.ts

src/theory/catalogs/
  scales.ts
  modes.ts
  chordQualities.ts
  lydianChromatic.ts

src/theory/engines/
  scaleEngine.ts
  harmonicFieldEngine.ts
  comparisonEngine.ts
  lydianChromaticEngine.ts

src/theory/dictionary/
  pt-BR.ts
  en.ts

This does not need to be done all at once. It can be gradual.

The most practical first step is:

src/theory/lydianChromatic/
  types.ts
  data.ts
  engine.ts
  examples.ts

And the UI feature can live separately:

src/components/lydianChromatic/
  LydianChromaticSection.tsx
  ChordTargetSelector.tsx
  LydianParentScalePanel.tsx
  TargetNotesPanel.tsx
  LydianScaleOrderPanel.tsx

How the Lydian Chromatic feature should fit the app

The Lydian Chromatic section should be a new tab, not a mutation of the existing "Scales", "Harmony", or "Modes" tabs.

Data model proposal

Use data first. Avoid hardcoding the class notes directly inside JSX.

export type LydianChromaticChordId =
  | 'maj7'
  | 'maj7Sharp5'
  | 'dom7'
  | 'dom7Alt'
  | 'min7'
  | 'halfDim7'
  | 'dim7'
  | 'sus4Flat9'

export type LydianChromaticScaleId =
  | 'lydian'
  | 'lydianAugmented'
  | 'lydianDiminished'
  | 'lydianFlat7'
  | 'auxiliaryAugmented'
  | 'auxiliaryDiminished'
  | 'auxiliaryDiminishedBlues'

export interface LydianChromaticChordTarget {
  id: LydianChromaticChordId
  symbolTemplate: string        // "Xmaj7", "X7alt", "Xm7b5"
  qualityLabel: string          // "major seventh", "altered dominant"
  genericTargetDegree: string   // e.g. "#5", "b9", "b5"; verify with teacher notes
  parentScaleHint: string       // text reference for the relationship
  preferredScaleIds: LydianChromaticScaleId[]
  notes?: string                // teacher-specific note / caveat
}

The class photo and notes should seed this table, but the data should remain easy to edit because some mappings must be verified against the teacher's explanation before being treated as final.

Why the Lydian Chromatic feature needs its own engine

The current computeScale(tonic, scaleId) pattern is built around selecting a tonic and one of four known scales. The Lydian Chromatic workflow needs a different input:

computeLydianChromatic({
  root: 'C',
  chordId: 'dom7Alt'
})

The output should not only be a scale. It should include:

{
  root: 'C',
  chordSymbol: 'C7alt',
  targetDegree: '#5',
  targetNote: 'G#',
  parentScale: {
    id: 'lydianAugmented',
    root: '...',
    notes: [...]
  },
  orderedScaleOptions: [
    { id: 'lydian', notes: [...], tensionLevel: 1 },
    { id: 'lydianAugmented', notes: [...], tensionLevel: 2 },
    ...
  ],
  exercisePrompt: 'Write 8 eighth notes including the 8th-order target note.'
}

This lets the UI stay simple and keeps the music logic testable.

Immediate implementation recommendations

Priority 1: Add the tab shell only

Add the new tab, title, empty state, and layout without complex theory first.

Files likely touched:

src/components/layout/TabBar.tsx
src/App.tsx
src/i18n/locales/pt-BR.ts
src/i18n/locales/en.ts
src/components/lydianChromatic/LydianChromaticSection.tsx

Priority 2: Create the Lydian Chromatic data model

Add typed data and a minimal engine.

Files:

src/theory/lydianChromatic/types.ts
src/theory/lydianChromatic/data.ts
src/theory/lydianChromatic/engine.ts

Priority 3: Reuse the existing enharmonic selector pattern

Do not rewrite the note selector from scratch. Either reuse TonicSelector directly or extract a more generic note selector from it.

Priority 4: Build the chord target buttons

Start with a small verified set:

Xmaj7
Xmaj7#5
X7
X7alt
Xm7
Xm7b5
Xdim7
X7sus4(b9)

The UI should show the generic form first (X7alt) and the concrete form after choosing root (C7alt).

Priority 5: Add parent-scale and target panels

Show:

selected chord
target/alvo
target note
parent scale name
parent scale notes
ordered scale options by increasing tension
short improvisation instruction

Suggested visual layout

[Lídio Cromático]

[Root selector: C C#/Db D D#/Eb...]

[Chord target buttons]
Xmaj7 | Xmaj7#5 | X7 | X7alt | Xm7 | Xm7b5 | Xdim7 | X7sus4(b9)

[Selected chord]
C7alt

[Target / Alvo]
Generic: #5
Concrete: G#

[Parent scale / Escala-mãe]
Lydian Augmented from: ...
Notes: ... ... ...

[Ordered scale options]
1. Lydian
2. Lydian Augmented
3. Lydian Diminished
4. Lydian b7
5. Auxiliary Augmented
6. Auxiliary Diminished
7. Auxiliary Diminished Blues

[Exercise]
Write one bar of 8 eighth notes for C7alt, including the target note.

Validation checklist

npm run build
npm run lint
The original four app tabs still work.
Selecting tonic still updates scales, harmonic field, modes, and comparison.
The new tab does not break localStorage.
Enharmonic buttons still allow choosing sharp or flat spelling independently.
Lydian Chromatic data is typed and not embedded in JSX.
The feature can be expanded by editing data files, not UI logic.
The explanation text can later move into dictionary/i18n keys.

Risks

Risk 1: Treating Lydian Chromatic as just another scale family

This would be too limiting. It needs chord-target logic, not only parent-scale logic.

Risk 2: Hardcoding uncertain teacher-board mappings

The board/photo notes should be preserved as editable seed data, not buried in components.

Risk 3: Mixing Russell terminology with generic jazz scale terminology

The UI should make it clear when a scale is part of the Russell/Lydian Chromatic workflow versus when it is a general jazz scale label.

Risk 4: Overbuilding the first version

The first version should be a useful study tool, not a complete implementation of the whole book.

Recommended next task

Implement the new Lydian Chromatic tab as a first vertical slice:

add tab
add chord quality buttons
add root selector
add target panel
add parent-scale panel
add ordered Lydian scale options
use typed seed data
keep all theory data editable

This gives the app a foundation for adding more teacher-specific harmony material later.