Code Structure Narrator

"Hear the logic, map the structure, and code without barriers."

Code Structure Narrator is a professional IntelliJ IDEA plugin designed to empower developers with visual impairments. By bridging the gap between raw code text and logical intent, it transforms how blind developers navigate, understand, and interact with complex Java projects.

---

🌟 The Vision: Beyond Accessibility

While this project began as an accessibility tool for blind developers, its core philosophy—Structure over Syntax—is a game-changer for everyone.

• Current MVP: A sophisticated "Narrator" that uses PSI and AI to explain code.
• The Future: Moving toward a Voice-Enabled Development Environment. Our prototype for voice-based code insertion suggests a future where any developer can code hands-free, increasing productivity and reducing repetitive strain for the entire developer community.

---

✨ Key Features

🟢 Tier 1: Instant Structural Awareness (PSI-based)

• Deep Context Tracking: Uses JetBrains' Program Structure Interface (PSI) to identify if you are in a class, a specific method, or a nested if/for block.
• Real-time Feedback: Announces your location as you move your cursor, providing an immediate mental map of the file.
• Multi-language Support: Fully localized logic for both English and Spanish.

🔵 Tier 2: AI Logic Interpretation (LLM-driven)

• Semantic Summarization: Powered by GPT-4o-mini, it explains the intent of the code in exactly one short, spoken sentence (max 120 chars).
• Intelligent Prompting: Differentiates between class purposes, method behaviors, and loop conditions to provide relevant insights.
• Shortcut: Alt + E (Explain Current Context)

🌍 Global Reach: Language Toggle

• Localization Service: Toggle between English and Spanish on the fly. All narration, fallback messages, and AI prompts adapt to the selected language.
• Shortcut: Dedicated Toolbar Action (EN/ES Toggle) or Alt + L.

🛠 Professional Demo Mode

• Platform-Native TTS: Utilizes Windows PowerShell System.Speech.Synthesis with specific regional voice selection (e.g., Microsoft Zira for English, Helena/Sabina for Spanish).
• Debounce & Cleanup: Advanced logic to prevent speech overlap and clean up technical symbols for a natural listening experience.

---

🏗 Technical Architecture

• JetBrains PSI: The "eyes" of the plugin, parsing the Abstract Syntax Tree (AST) for precise location tracking.
• OpenAI API: The "brain" of the plugin, translating code into human-readable intent.
• Service-Oriented Design:
  • LanguageService: Manages regional settings.
  • NarratorStateService: Centralized state management using the Observer pattern.
  • AnnouncementService: Bridge to native Screen Readers (NVDA/JAWS).
  • DemoSpeechService: High-quality system-level audio output.

---

🚀 Getting Started

Prerequisites

• IntelliJ IDEA 2024.1+
• Java 17
• OPENAI_API_KEY set as an environment variable.

Build & Run

./gradlew buildPlugin
./gradlew runIde

Usage

1. Navigate: Move the cursor. The plugin will announce the structural context (Tier 1).
2. Explain: Press Alt + E to hear the AI-generated intent of the block (Tier 2).
3. Language: Click the EN/ES button in the toolbar to switch languages.
4. Demo: Enable Tools > Demo Mode to hear direct system audio if no screen reader is present.

---

🗺 Roadmap: What's Next?

• Voice-to-Code Prototype: Expanding the currently experimental voice-insertion feature into a full-fledged command system.
• Universal Productivity: Evolving the structural narrator into a "Summary Tool" for all developers to quickly audit large codebases.
• Expanded Support: Bringing PSI-level narration to Kotlin, Python, and C++.

---

Collaborators

• [TEAM] Zero Shot F5
• Andres Torrez | Michelle Gelves | Raúl Machaca | Mirae Kang