Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

devkeys Documentation

Type faster. Code smarter.
A privacy-first typing trainer for developers.

Welcome to the documentation. This folder contains comprehensive design, architecture, and contribution materials for the project.

📖 Documentation Index

Section Description
Overview & Principles Vision, core principles, and what makes DevKeys different
Goals & Features Success metrics and feature roadmap
Syntax & Architecture Technical architecture, data flow, and syntax pipeline
NFR & MVP Plan Non-functional requirements and MVP scope
Rust Components WASM engine architecture and Rust roadmap
Observability Tracing, telemetry, and debugging strategies
Testing & CI Test strategy and continuous integration
Licensing & Community License, contribution model, and governance
Glossary Key technical terms and definitions
Contributing How to contribute code, prompts, and ideas

🎯 Current Status

✅ Fully Implemented

Core Typing Experience

  • Real-time character-by-character feedback with syntax highlighting
  • Live metrics: WPM, accuracy, completion percentage, elapsed time
  • Tab-to-indent assistance for code alignment
  • Keyboard shortcuts (Cmd/Ctrl + R to restart, Cmd/Ctrl + K for explorer)

Prompt Management

  • Built-in algorithm and pattern prompts for multiple languages
  • Custom prompt creation, editing, and deletion
  • File-based organization with language grouping
  • Explorer sidebar with search and filtering

Analytics & History

  • IndexedDB session persistence (all data stays local)
  • Expandable stats panel with detailed metrics
  • Per-prompt session history tracking
  • Metrics include: keystrokes, correct/incorrect chars, duration

UI & UX

  • Desktop-like window interface with drag, minimize, maximize
  • Syntax theme switcher (Dark+, Light+, GitHub themes, Monokai)
  • Smooth animations via Framer Motion
  • Responsive layout with adaptive font sizing

Engine

  • Rust WASM scoring engine for high-performance diff calculation
  • TypeScript fallback for development without WASM
  • Real-time feedback generation (<50ms latency)

🚧 In Progress

  • Expanded prompt packs (more languages and patterns)
  • Statistics export (CSV/JSON)
  • Streak tracking and goal setting
  • Heatmap visualizations for error patterns

🗺️ Future Roadmap

Phase 2: Advanced Learning

  • Adaptive difficulty based on performance
  • Weak-point identification and targeted practice
  • Interview preparation mode
  • Code structure pattern recognition

Phase 3: Community & Content

  • User-submitted prompt pack sharing (privacy-preserving)
  • Community leaderboards (opt-in, anonymous)
  • AI-powered prompt generation (behind privacy proxy)
  • Multi-language localization

🏗️ Architecture Overview

DevKeys uses a modular architecture optimized for performance and privacy:

┌─────────────────────────────────────────────────┐
│                  React UI                        │
│  (Zustand state, Tailwind styling, Framer)      │
├─────────────────────────────────────────────────┤
│              highlight.js                        │
│         (Syntax tokenization)                    │
├─────────────────────────────────────────────────┤
│          Rust WASM Engine                        │
│  (Diff calculation, scoring, feedback)           │
├─────────────────────────────────────────────────┤
│           IndexedDB Storage                      │
│    (Sessions, custom prompts, settings)          │
└─────────────────────────────────────────────────┘

Key Design Decisions:

  • Custom editor instead of Monaco to minimize bundle size and maintain full control over typing behavior
  • highlight.js provides syntax colors without the overhead of a full language server
  • Rust WASM for performance-critical diff algorithms while keeping TypeScript fallback for dev ergonomics
  • IndexedDB ensures all data stays on-device with no network dependency

🔧 Development Workflow

Adding New Prompts

  1. Add your snippets to apps/web/src/content/packs/your-pack.json
  2. Register the pack in apps/web/src/content/localPacks.ts
  3. Follow the schema in CONTRIBUTING.md

Modifying the Engine

  1. Edit Rust code in crates/engine/src/
  2. Run pnpm build:wasm to recompile
  3. Test changes with cargo test -p devkeys_engine

UI Components

  • All components follow feature-based organization
  • Styles use Tailwind + TypeScript style objects
  • Hooks encapsulate complex logic (see features/*/hooks/)

🤝 Contributing

We welcome contributions of all kinds:

  • 🐛 Bug fixes and improvements
  • ✨ New features and enhancements
  • 📝 New prompt packs and content
  • 📚 Documentation improvements
  • 🎨 UI/UX enhancements

See CONTRIBUTING.md for detailed guidelines.

📊 Metrics & Goals

Metric Target Current Status
Keystroke latency ≤50ms ✅ Achieved
First load time <2s ✅ Achieved
Bundle size <500KB (gzipped) ✅ Achieved
WASM overhead <100KB ✅ Achieved
Supported languages 10+ ✅ Achieved

🔗 Quick Links

Happy typing! ⌨️✨