# heyito/ito architecture

> Architecture diagram of the GitHub repository heyito/ito, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heyito/ito
- Repository: https://github.com/heyito/ito

## Overview

##### Project type and purpose
- This is “Ito,” a cross-platform desktop voice-dictation app built on Electron.
- It combines a multi-process client (main, renderer, preload, native binaries), a gRPC transcription server (with a database and AWS infra), and native components in Rust/Swift.

##### File structure
- Top-level directories:
- app/ – Electron renderer (React + Zustand + Tailwind)
- lib/ – Shared TypeScript code for Electron main, preload, media, protocol, types, utils
- native/ – Rust & Swift binaries for audio capture, global key listening, text insertion, app context
- server/ – gRPC transcription server (Node.js + Bun + TypeScript), DB code, migrations, infra-as-code (AWS CDK)
- Key build/config files: electron.vite.config.ts, electron-builder.config.js, tsconfig.*, Dockerfiles, build-scripts
- Workflow: user interaction → Electron main → native binaries → gRPC client → server → AI model → back through main → native text writer → target app

##### Extract extra context from README
- Client architecture:
- Main process: system integration, permissions, orchestrates native components
- Renderer process: React UI (components, store, styles)
- Preload: secure IPC bridge
- Native components: Rust/Swift for performance
- Server:
- gRPC API, database (PostgreSQL via Bun/TypeORM/SQLite in dev), migrations, AWS infra (Fargate, Lambdas, Firehose, OpenSearch)
- Key external services: Auth0, AWS (Cognito, Firehose, OpenSearch), LLM/A I transcription providers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Local Machine Zone
    subgraph "Local Machine"
        direction TB
        User["User (Keyboard & Mic)"]:::external

        subgraph "Electron Client" 
            direction TB
            subgraph "Renderer Process"
                direction TB
                Renderer["React UI (app/)"]:::client
            end
            subgraph "Main Process"
                direction TB
                Main["Electron Main (lib/main/)"]:::client
            end
            subgraph "Preload Bridge"
                direction TB
                Preload["Preload IPC (lib/preload/)"]:::client
            end
            subgraph "Shared TS Libraries"
                direction TB
                SharedLib["Shared Code (lib/)"]:::client
            end
            subgraph "Native Components"
                direction TB
                KeyListener["Global Key Listener"]:::native
                AudioRecorder["Audio Recorder"]:::native
                TextWriter["Text Writer"]:::native
                AppDetector["Active-App Detector"]:::native
                SelectedText["Selected-Text Reader"]:::native
                MacTextReader["macOS Text Reader"]:::native
            end
            subgraph "Local Storage"
                direction TB
                LocalDB["SQLite (lib/main/sqlite/)"]:::server
            end
        end
    end

    %% Cloud Zone
    subgraph "Cloud"
        direction TB
        subgraph "gRPC Transcription Server"
            direction TB
            ServerEntry["Server Entry (server/src/server.ts, index.ts)"]:::server
            Protos["Proto & Stubs (server/src/ito.proto, generated/)"]:::server
            subgraph "API Layer"
                direction TB
                Validation["Validation Interceptor"]:::server
                Logging["Logging Interceptor"]:::server
                ErrorInt["Error Interceptor"]:::server
            end
            BLService["Business Logic (itoService)"]:::server
            DBRepo["DB & Repo (server/src/db.ts, models.ts, repo.ts)"]:::server
            Migrations["Migrations (server/src/migrations/)"]:::server
        end

        subgraph "AWS Infrastructure"
            direction TB
            CDK["CDK Stacks (server/infra/)"]:::aws
            subgraph "Infra Lambdas"
                direction TB
                FirehoseLambda["Firehose Transform"]:::aws
                OpenSearchLambda["OpenSearch Bootstrap"]:::aws
                MigLambda["Run Migration"]:::aws
            end
        end

        subgraph "External Services"
            direction TB
            AIProviders["AI Model Providers"]:::external
            Auth0["Auth0 (OAuth)"]:::external
        end
    end

    %% Data Flows
    User -->|"trigger"| KeyListener
    KeyListener -->|"hotkey event"| Main
    Main -->|"record audio"| AudioRecorder
    AudioRecorder -->|"audio stream"| Main
    Main -->|"gRPC request"| ServerEntry
    ServerEntry -->|"validate/log"| Validation
    Validation -->|'itoService'| BLService
    BLService -->|"repo calls"| DBRepo
    DBRepo -->|"reads/writes"| Migrations
    BLService -->|"transcribe"| AIProviders
    AIProviders -->|"text"| BLService
    BLService -->|"response"| ServerEntry
    ServerEntry -->|"gRPC response"| Main
    Main -->|"inject text"| TextWriter
    Main -->|"detect app"| AppDetector
    Main -->|"read selected text"| SelectedText
    Main -->|"invoke mac reader"| MacTextReader
    Main -->|"state event"| Preload
    Preload -->|"IPC"| Renderer
    Renderer -->|"settings/history"| Main
    Main -->|"local DB"| LocalDB
    Main -->|"cloud sync"| ServerEntry
    ServerEntry -->|"deploy"| CDK
    CDK -->|"invoke"| FirehoseLambda
    CDK -->|"invoke"| OpenSearchLambda
    CDK -->|"invoke"| MigLambda
    BLService -->|"logs"| OpenSearchLambda

    %% Click Events
    click Renderer "https://github.com/heyito/ito/tree/dev/app/"
    click Main "https://github.com/heyito/ito/tree/dev/lib/main/"
    click Preload "https://github.com/heyito/ito/tree/dev/lib/preload/"
    click SharedLib "https://github.com/heyito/ito/tree/dev/lib/"
    click KeyListener "https://github.com/heyito/ito/tree/dev/native/global-key-listener/"
    click AudioRecorder "https://github.com/heyito/ito/tree/dev/native/audio-recorder/"
    click TextWriter "https://github.com/heyito/ito/tree/dev/native/text-writer/"
    click AppDetector "https://github.com/heyito/ito/tree/dev/native/active-application/"
    click SelectedText "https://github.com/heyito/ito/tree/dev/native/selected-text-reader/"
    click MacTextReader "https://github.com/heyito/ito/tree/dev/native/macos-text/"
    click ServerEntry "https://github.com/heyito/ito/blob/dev/server/src/server.ts"
    click Protos "https://github.com/heyito/ito/blob/dev/server/src/ito.proto"
    click Validation "https://github.com/heyito/ito/blob/dev/server/src/services/validationInterceptor.ts"
    click Logging "https://github.com/heyito/ito/blob/dev/server/src/services/loggingInterceptor.ts"
    click ErrorInt "https://github.com/heyito/ito/blob/dev/server/src/services/errorInterceptor.ts"
    click BLService "https://github.com/heyito/ito/blob/dev/server/src/services/ito/itoService.ts"
    click DBRepo "https://github.com/heyito/ito/blob/dev/server/src/db.ts"
    click Migrations "https://github.com/heyito/ito/tree/dev/server/src/migrations/"
    click CDK "https://github.com/heyito/ito/tree/dev/server/infra/"
    click FirehoseLambda "https://github.com/heyito/ito/blob/dev/server/infra/lambdas/firehose-transform.ts"
    click OpenSearchLambda "https://github.com/heyito/ito/blob/dev/server/infra/lambdas/opensearch-bootstrap.ts"
    click MigLambda "https://github.com/heyito/ito/blob/dev/server/infra/lambdas/run-migration.ts"
    click LocalDB "https://github.com/heyito/ito/tree/dev/lib/main/sqlite/"

    %% Styles
    classDef client fill:#ccffcc,stroke:#006600,color:#003300
    classDef server fill:#cce5ff,stroke:#004080,color:#001f4d
    classDef native fill:#ffe0b3,stroke:#cc7a00,color:#663c00
    classDef aws fill:#e0e0e0,stroke:#666666,color:#333333
    classDef external fill:#e5ccff,stroke:#800080,color:#4d004d
```
