Sketchi

What is Sketchi?

Sketchi is a diagram and icon library toolkit that transforms SVGs into hand-drawn Excalidraw assets. Build icon libraries, generate AI-powered diagrams, and export production-ready .excalidrawlib files.

Key Features:

Icon Library Generator - Upload SVGs, customize styles, export as Excalidraw libraries
AI Diagram Generation - Convert natural language to flowcharts, architecture diagrams, and more
Hand-drawn Rendering - Apply sketchy, hand-drawn aesthetics to any SVG
Real-time Collaboration - Powered by Convex for instant sync

Live at: https://sketchi.app/

Screenshots

<img src="docs/screenshots/home.png" alt="Sketchi Home" width="800" /> Home - Tool selection dashboard <img src="docs/screenshots/library-generator.png" alt="Icon Library Generator" width="800" /> Icon Library Generator - Build and export Excalidraw libraries <img src="docs/screenshots/web-based-inline-generator-god-hates-js.png" alt="AI Diagram Generator" width="800" /> AI Diagram Generator - Convert natural language to flowcharts and diagrams

What is Sketchi?
Screenshots
Architecture
Model Strategy
Features
Quick Start
Development
Testing
Project Structure
License

Architecture

<img src="docs/screenshots/architecture.png" alt="Sketchi Architecture" width="800" /> Architecture - System design and data flow

Monorepo Structure:

Directory	Purpose
`apps/web`	Next.js 16 frontend with React 19
`packages/backend`	Convex functions, actions, and database schema
`packages/env`	Shared environment variable validation
`packages/config`	Shared TypeScript configuration
`tests/e2e`	End-to-end tests with Stagehand

Data Flow:

User interacts with the Next.js frontend
Frontend calls Convex functions via React hooks (useQuery, useMutation)
Convex functions handle business logic, AI calls, and database operations
File uploads stored in Convex storage, metadata in Convex database
AI diagram generation uses Vercel AI SDK through Convex actions

Model Strategy

Sketchi uses a multi-model approach via OpenRouter to balance reasoning, vision, and latency.

Role	Model	Primary Use Case
Brain	`google/gemini-3-flash-preview`	Diagram generation, structural analysis, and visual grading.
Driver	`google/gemini-2.5-flash-lite`	E2E test execution (Stagehand) and UI interaction.
Experimental	`google/gemini-3.1-flash-lite-preview`	Low-latency validation, JSON repair, and classification.
Fallback	`z-ai/glm-4.7`	High-reliability secondary model for diagram retries.

Features

Icon Library Generator

SVG Upload - Drag and drop or select multiple SVG files
Style Customization - Adjust stroke color, fill style, roughness, and opacity
Hand-drawn Conversion - Transform clean SVGs into sketchy, hand-drawn versions
Excalidraw Export - Download as .excalidrawlib for direct import

AI Diagram Generation

Natural Language Input - Describe your diagram in plain English
Multiple Chart Types - Flowcharts, architecture diagrams, decision trees
Intermediate Format - Structured JSON representation for predictable layouts
Auto Layout - Dagre-based automatic node positioning

Export Options

PNG Export - High-resolution PNG via Browserbase rendering
Excalidraw Library - Reusable icon sets for Excalidraw
Share Links - Generate shareable Excalidraw links

Quick Start

Prerequisites

Bun 1.3.5+
Convex CLI

Installation

# Clone the repository
git clone https://github.com/anand-testcompare/sketchi.git
cd sketchi

# Install dependencies
bun install

# Set up Convex (follow prompts to create/link project)
bun run dev:setup

# Start development servers
bun run dev

The app will be available at http://localhost:3001.

Environment Variables

Create .env.local in apps/web/:

NEXT_PUBLIC_CONVEX_URL=<your-convex-deployment-url>

For AI features and testing, see .env.e2e.example for additional variables.

OpenCode Plugin

The publishable OpenCode plugin package lives under packages/opencode-excalidraw and is published to npm as @sketchi-app/opencode-excalidraw.

Notes:

Install Playwright browsers once per machine:
- npx playwright install
Override API base with SKETCHI_API_URL.
Tools exposed: diagram_from_prompt, diagram_tweak, diagram_restructure, diagram_to_png, diagram_grade.
Publish channels: next is used for pre-release iteration testing; latest publishes when the plugin release PR is merged.
Install and use from any repo:

npm i @sketchi-app/opencode-excalidraw

Add to opencode.json:

{
  "plugin": ["@sketchi-app/opencode-excalidraw"]
}

Development

Commands

Command	Description
`bun run dev`	Start all apps (frontend + Convex)
`bun run dev:web`	Start frontend only
`bun run dev:server`	Start Convex backend only
`bun run build`	Build all apps
`bun run check-types`	TypeScript type checking
`bun x ultracite fix`	Format code with Biome
`bun x ultracite check`	Lint check with Biome

Code Quality

This project uses Ultracite (Biome preset) for formatting and linting:

# Format and fix issues
bun x ultracite fix

# Check for issues
bun x ultracite check

Testing

Sketchi follows a test hierarchy: API tests > E2E tests > unit tests (last resort).

API Tests (Convex Functions)

Located in packages/backend/convex/*.test.ts. Uses Vitest + convex-test.

# Run all Convex tests
cd packages/backend
bun run test

# Watch mode
bun run test:watch

# Generate report
bun run test:report

Test files:

visualGrading.test.ts - Vision-based diagram grading
export.test.ts - PNG export via Browserbase
diagramGenerateFromIntermediate.test.ts - Diagram rendering
diagramLayout.test.ts - Auto-layout algorithms
arrowOptimization.test.ts - Arrow path optimization

E2E Tests (Stagehand + Playwright)

Located in tests/e2e/. Uses Stagehand 3 with LLM-based visual grading.

# Set up environment
cp tests/e2e/.env.example tests/e2e/.env.e2e
# Fill in OPENROUTER_API_KEY, BROWSERBASE_API_KEY, etc.

# Run scenario
cd tests/e2e
bun run visual-sanity

Scenarios:

visual-sanity.ts - Visual sweep across light/dark modes
icon-library-generator-happy-path.ts - Full user flow test

CI/CD

Backend tests: Run on every PR via GitHub Actions
E2E tests: Run against preview deployments
Reports: Uploaded as artifacts to GitHub

Project Structure

sketchi/
├── apps/
│   └── web/                    # Next.js 16 frontend
│       ├── src/
│       │   ├── app/            # App Router pages
│       │   ├── components/     # React components
│       │   └── lib/            # Utilities
│       └── public/             # Static assets
├── packages/
│   ├── backend/                # Convex backend
│   │   ├── convex/             # Functions, schema, tests
│   │   └── lib/                # Shared utilities
│   ├── config/                 # Shared TypeScript config
│   └── env/                    # Environment validation
├── tests/
│   └── e2e/                    # Stagehand E2E tests
├── docs/                       # Documentation
├── turbo.json                  # Turborepo config
└── package.json                # Root workspace config

License

MIT License - see LICENSE for details.

Name	issue-grooming
Description	Use when a GitHub issue needs grooming into an implementation-ready spec with dependencies, tests, and acceptance criteria.

issue-grooming

SKILL.md