Project Structure Documentation

Overview

This document details the complete structure of the transcribe.dev monorepo, including all active directories, their purposes, and key files. transcribe.dev provides system-wide voice-to-text dictation with AI enhancement.

Root Structure

transcribe-dev/
├── apps/                      # Application packages
│   ├── transcribe/            # Web app / Dashboard
│   ├── desktop/               # Electron dictation app
│   └── api/                   # Hono API (Cloudflare Workers)
├── convex/                    # Shared Convex backend
├── packages/                  # Shared packages
│   ├── ui/                    # ShadCN UI components
│   ├── shared/                # Shared types and constants
│   ├── landing-page-template/ # Landing page template
│   └── typescript-config/     # Shared TS configs
├── docs/                      # Documentation
├── turbo.json                 # Turborepo configuration
├── pnpm-workspace.yaml        # PNPM workspace config
├── package.json               # Root package.json
├── biome.json                 # Biome formatter/linter config
└── CLAUDE.md                  # AI assistant guide

Applications (`/apps`)

`/apps/transcribe` - Web App / Dashboard

The web application with user dashboard for transcribe.dev.

transcribe/
├── app/                      # Next.js App Router
│   ├── api/                  # API Routes
│   │   └── health/           # Health check endpoint
│   ├── layout.tsx            # Root layout
│   ├── page.tsx              # Landing page (uses shared template)
│   ├── not-found.tsx         # 404 page
│   ├── robots.ts             # SEO robots.txt
│   ├── sitemap.ts            # SEO sitemap
│   └── favicon.ico           # Static favicon
├── next.config.js            # Next.js config
├── package.json              # Dependencies
├── tailwind.config.ts        # Tailwind config
└── tsconfig.json             # TypeScript config

`/apps/desktop` - Electron Dictation App (Phase 1)

The core product: a system-wide voice dictation tool with AI cleanup.

desktop/
├── src/
│   ├── main/                 # Electron main process
│   │   └── index.ts          # Entry point, window/hotkey management
│   ├── preload/              # Context bridge (IPC)
│   │   ├── index.ts          # Preload script with API bridge
│   │   └── index.d.ts        # TypeScript declarations
│   └── renderer/             # React UI (Vite)
│       ├── index.html        # HTML entry point
│       └── src/
│           ├── App.tsx       # Main React component
│           ├── main.tsx      # React entry point
│           └── styles/
│               └── globals.css
├── resources/                # App icons and assets
├── electron.vite.config.ts   # electron-vite configuration
├── electron-builder.yml      # Build/packaging config
├── package.json              # Dependencies
├── tsconfig.json             # Root TypeScript config
├── tsconfig.node.json        # Node-specific TS config (main/preload)
└── tsconfig.web.json         # Web TS config (renderer)

Current Implementation Status:

Window management with 400x600 initial size
Global hotkey registration (CommandOrControl+Shift+Space)
IPC bridge for dictation state, hotkey, text injection APIs
Basic React UI showing dictation states (idle, listening, processing, injecting, error)
Tailwind CSS v4 styling

Planned (Not Yet Implemented):

Audio capture from microphone
Deepgram WebSocket streaming for STT
Claude Haiku for AI cleanup
nut.js for text injection
System tray management
Settings panel

Key Technologies:

Framework: Electron 33+ with electron-vite
Renderer: React 19 + Vite + TypeScript
STT: Deepgram WebSocket streaming (planned)
Text Injection: nut.js (planned)
Styling: Tailwind CSS v4

Convex Backend (`/convex`)

Shared backend for real-time data sync across all user devices.

convex/
├── _generated/               # Auto-generated Convex types
├── schema.ts                 # Database schema
├── users.ts                  # User queries/mutations
├── dictionaries.ts           # Personal dictionary CRUD
├── snippets.ts               # Voice shortcuts/expansions
├── appTones.ts               # Per-app tone settings
├── history.ts                # Dictation history
└── voice.ts                  # Actions: transcribe, cleanup

Schema Overview:

Table	Purpose
`users`	User profiles, settings, subscription plan
`dictionaries`	Personal word dictionary for accuracy
`snippets`	Voice shortcuts (trigger → expansion)
`appTones`	Per-application tone settings
`history`	Dictation history with raw/cleaned text

Packages (`/packages`)

`/packages/ui` - Shared UI Components

ShadCN UI component library shared across apps.

ui/
├── components/            # ShadCN UI components
├── primitives/            # Base UI primitives
├── static/                # Static assets (logos, etc.)
├── hooks/                 # Shared React hooks
├── lib/                   # UI utilities
└── package.json

`/packages/shared` - Shared Types & Constants

Common TypeScript types and constants used across apps.

shared/
├── src/
│   ├── types/
│   │   ├── index.ts       # Type exports
│   │   ├── user.ts        # User, UserSettings, UserPlan
│   │   └── dictation.ts   # DictionaryWord, Snippet, AppTone, etc.
│   └── constants.ts       # App constants (hotkeys, languages, plans)
└── package.json

Exports:

@workspace/shared/types - All TypeScript interfaces
@workspace/shared/constants - App constants

`/packages/landing-page-template` - Landing Page System

Shared landing page template with type-safe configuration.

landing-page-template/
├── src/
│   ├── components/        # Template components
│   ├── examples/
│   │   └── transcribe-config.ts # transcribe.dev configuration
│   └── types/             # TypeScript interfaces
└── package.json

`/packages/typescript-config` - Shared TS Configs

typescript-config/
├── base.json              # Base TypeScript config
├── nextjs.json            # Next.js specific config
├── react-library.json     # React library config
└── package.json

Documentation (`/docs`)

docs/
├── README.md                     # Documentation index
├── transcribe-dev-bootstrap-PRD.md   # PRD (PRIORITY)
├── TENETS.md                     # Core development principles
├── architecture/
│   ├── PROJECT_STRUCTURE.md      # This file
│   └── PHASE1_IMPLEMENTATION.md  # Phase 1 technical details
├── development/
│   ├── GIT_PREFERENCES.md        # Git workflow
│   ├── TYPESCRIPT_BEST_PRACTICES.md
│   ├── SHADCN.md                 # UI component guide
│   └── UI_STANDARDS.md           # UI/UX guidelines
└── future/
    └── voice-synthesis/          # Phase 2 documentation

Key Configuration Files

Root Level

turbo.json - Turborepo pipeline configuration
pnpm-workspace.yaml - Workspace package definitions
biome.json - Code formatting and linting rules
.env.example - Environment variable template

Environment Variables

Convex Backend:

CONVEX_DEPLOYMENT=your-deployment-name
WORKOS_CLIENT_ID=your-workos-client-id
DEEPGRAM_API_KEY=your-deepgram-key
ANTHROPIC_API_KEY=your-anthropic-key

Web App (talk):

NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
WORKOS_CLIENT_ID=your-workos-client-id
WORKOS_API_KEY=your-workos-api-key
WORKOS_COOKIE_PASSWORD=your-32-char-random-string
NEXT_PUBLIC_WORKOS_REDIRECT_URI=http://localhost:3012/callback

Scripts Overview

Development

pnpm dev              # Start all development servers
pnpm dev:talk         # Start marketing site only
pnpm dev:desktop      # Start desktop app only
pnpm build            # Build all packages
pnpm start            # Start production servers

Code Quality

pnpm lint             # Run linter
pnpm lint:fix         # Auto-fix lint issues
pnpm format           # Format code
pnpm check            # Run all Biome checks
pnpm typecheck        # TypeScript type checking

UI Components

pnpm ui:add <component>   # Add ShadCN UI component

Convex

pnpm convex dev       # Start Convex development
pnpm convex deploy    # Deploy Convex functions

Port Configuration

Application	Development Port
Marketing Site (talk)	3012
Desktop Renderer	5173 (Vite default)
Convex Dashboard	3210

Development Workflow

Phase 1: Desktop App Development

Setup Convex: pnpm create convex@latest
Setup Desktop: pnpm create electron-vite in apps/desktop
Install Dependencies: Deepgram, Anthropic SDK, nut.js
Implement Core Features:
- System tray + global hotkeys
- Audio capture + Deepgram streaming
- Claude Haiku cleanup
- Text injection

Adding New Features

Define types in /packages/shared
Add Convex schema/functions in /convex
Implement UI in /apps/desktop/src/renderer
Add main process handlers in /apps/desktop/src/main

Last updated: December 2024

On this page