Skip to content

docs: create WIKI with architecture overview, component diagram, and contribution workflow #41

@chernistry

Description

@chernistry

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:

  1. User types in wrong layout
  2. EventMonitor captures keystrokes via CGEventTap
  3. Buffer accumulates characters until word boundary (space, punctuation)
  4. LanguageDetector analyzes the buffered text
  5. If detected language doesn't match current layout → correction needed
  6. CorrectionEngine maps characters using LayoutMappings
  7. Corrected text replaces original via Accessibility API (AXUIElement)
  8. Notification posted for UI feedback

Page 4: Adding a New Language

Step-by-step guide:

  1. Create mapping file in RightLayout/Sources/Engine/LayoutMappings/
  2. Define QWERTY ↔ target layout character map
  3. Handle shift states and special characters
  4. Add test cases to tests/test_cases.json
  5. Register the new layout in CorrectionEngine
  6. 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

  1. Enable Wiki on the GitHub repo (Settings → Features → Wikis)
  2. Create each page listed above
  3. Add diagrams (can use Mermaid in GitHub Wiki)
  4. Link to Wiki from README
  5. Add "Contributing" section to README pointing to Wiki

Acceptance Criteria

  • GitHub Wiki is enabled
  • Architecture overview page with component diagram exists
  • Correction pipeline page explains the full flow
  • "Adding a Language" guide is complete and accurate
  • Testing guide covers running and writing tests
  • Contributing page covers the full PR workflow
  • README links to the Wiki

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershacktoberfestHacktoberfest eligiblehelp wantedExtra attention is needed

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions