Problem
New contributors have no way to understand the RightLayout codebase without reading every file. There is no architecture documentation, no component diagram, and no contributor guide beyond the basic README.
Proposed Solution
Enable the GitHub Wiki and create the following pages:
Page 1: Home
Overview of RightLayout, links to all other wiki pages.
Page 2: Architecture Overview
┌─────────────────────────────────────────────┐
│ RightLayout │
├─────────────────────────────────────────────┤
│ UI Layer │
│ ├── MenuBarView (system tray icon) │
│ ├── SettingsView (preferences) │
│ └── OnboardingView (first-run setup) │
├─────────────────────────────────────────────┤
│ Engine Layer │
│ ├── EventMonitor (keystroke capture) │
│ ├── CorrectionEngine (layout detection) │
│ ├── LanguageDetector (text analysis) │
│ └── LayoutMappings/ (char tables) │
├─────────────────────────────────────────────┤
│ Core Layer │
│ ├── LaunchAtLogin (login item mgmt) │
│ ├── AccessibilityMgr (permission mgmt) │
│ ├── UpdateChecker (version check) │
│ └── Settings (UserDefaults) │
├─────────────────────────────────────────────┤
│ macOS APIs │
│ ├── CGEventTap (global key events) │
│ ├── TISInputSource (layout detection) │
│ ├── AXUIElement (text replacement) │
│ └── SMAppService (login items) │
└─────────────────────────────────────────────┘
Page 3: Correction Pipeline
Step-by-step flow:
- User types in wrong layout
EventMonitor captures keystrokes via CGEventTap
- Buffer accumulates characters until word boundary (space, punctuation)
LanguageDetector analyzes the buffered text
- If detected language doesn't match current layout → correction needed
CorrectionEngine maps characters using LayoutMappings
- Corrected text replaces original via Accessibility API (
AXUIElement)
- Notification posted for UI feedback
Page 4: Adding a New Language
Step-by-step guide:
- Create mapping file in
RightLayout/Sources/Engine/LayoutMappings/
- Define QWERTY ↔ target layout character map
- Handle shift states and special characters
- Add test cases to
tests/test_cases.json
- Register the new layout in
CorrectionEngine
- Test with
swift test --filter NewLanguage
Page 5: Testing Guide
- How to run tests:
swift test
- How to run specific tests:
swift test --filter TestName
- Test structure: unit tests vs integration tests
- How to add test cases to
test_cases.json
- Coverage reporting
Page 6: Contributing
- Fork & clone workflow
- Branch naming:
feat/description, fix/description
- PR checklist
- Code style (SwiftLint rules)
- How to test accessibility features (requires granting permissions)
Steps to Implement
- Enable Wiki on the GitHub repo (Settings → Features → Wikis)
- Create each page listed above
- Add diagrams (can use Mermaid in GitHub Wiki)
- Link to Wiki from README
- Add "Contributing" section to README pointing to Wiki
Acceptance Criteria
Problem
New contributors have no way to understand the RightLayout codebase without reading every file. There is no architecture documentation, no component diagram, and no contributor guide beyond the basic README.
Proposed Solution
Enable the GitHub Wiki and create the following pages:
Page 1: Home
Overview of RightLayout, links to all other wiki pages.
Page 2: Architecture Overview
Page 3: Correction Pipeline
Step-by-step flow:
EventMonitorcaptures keystrokes viaCGEventTapLanguageDetectoranalyzes the buffered textCorrectionEnginemaps characters usingLayoutMappingsAXUIElement)Page 4: Adding a New Language
Step-by-step guide:
RightLayout/Sources/Engine/LayoutMappings/tests/test_cases.jsonCorrectionEngineswift test --filter NewLanguagePage 5: Testing Guide
swift testswift test --filter TestNametest_cases.jsonPage 6: Contributing
feat/description,fix/descriptionSteps to Implement
Acceptance Criteria