Graphini

AI diagram workspace for turning rough ideas into editable Mermaid diagrams.

Built with Cowork for teams that need architecture, process, and product diagrams to stay editable after the first draft.

Why · Features · Quick Start · Configuration · API · Development

What Is Graphini?

Graphini is an open-source AI diagram workspace. Describe a system, workflow, schema, or handoff in plain English, then edit the generated Mermaid source beside the rendered diagram.

Unlike image-first diagram tools, Graphini keeps the diagram as text. That means you can repair it, diff it, save it with project docs, export it for slides or tickets, and keep iterating after the first AI draft.

Why Graphini

Most AI diagram tools produce a picture. Pictures are easy to share, but hard to review, version, or regenerate from source.

Graphini is built for the messy middle between "we should diagram this" and "this belongs in docs":

• Start with language - prompt the assistant with architecture notes, process descriptions, ERD requirements, deployment maps, or incident timelines.
• Keep the source - Mermaid remains visible and editable, so the diagram can live in docs and git instead of becoming a frozen canvas.
• Repair and iterate - use chat, syntax-aware repair, and model selection to refine a broken or incomplete diagram.
• Work in a workspace - keep diagrams, chat, notes, document state, collaborators, and exports connected.
• Bring real cloud context - bundled icon support helps infrastructure diagrams look like actual architecture, not placeholder boxes.

Use Graphini when you want a diagram that can be generated quickly, edited precisely, and handed off as code.

Features

AI diagram generation

• Natural-language prompts to Mermaid diagrams
• Streaming chat interface powered by the Vercel AI SDK
• Model/provider settings for OpenAI, Anthropic, OpenRouter, and Gemini paths
• Image/audio upload routes for richer diagram context

Mermaid workspace

• Mermaid source editor with rendered preview
• Workspace, canvas, edit, and view routes
• Diagram repair and error analysis endpoints
• Export-oriented UI for SVG, PNG, Mermaid, and handoff assets

Persistence and collaboration

• PostgreSQL-backed users, workspaces, conversations, messages, files, memories, credits, and settings
• Drizzle ORM with checked-in SQL schema and migrations
• Workspace collaborators API
• User preferences, app settings, model lab, and admin endpoints

Product surface

• Public landing page and authenticated app entry
• Magnova Auth cookie flow with local/dev auth fallback
• Admin panel with provider credential management
• OpenAPI spec for external integrations
• MermaidSeqBench harness for evaluating natural-language-to-Mermaid sequence diagram generation

Screenshots

Tech Stack

Quick Start

Prerequisites

• Node.js 24+
• pnpm 10+
• PostgreSQL database
• At least one AI provider key, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or GEMINI_API_KEY

Install

git clone https://github.com/omkarbhad/graphini.git
cd graphini
pnpm install
cp .env.example .env

Fill in DATABASE_URL, COOKIE_SECRET, and whichever provider keys you want to use.

Database

Apply the checked-in schema and migrations:

psql "$DATABASE_URL" -f database/schema.sql
psql "$DATABASE_URL" -f database/v2-schema.sql
psql "$DATABASE_URL" -f database/add-app-settings.sql
psql "$DATABASE_URL" -f database/add-admin-settings.sql
psql "$DATABASE_URL" -f database/add-files-persistence.sql
psql "$DATABASE_URL" -f database/add-files-support.sql
psql "$DATABASE_URL" -f database/add-user-memories.sql
psql "$DATABASE_URL" -f database/add-gemini-provider.sql
psql "$DATABASE_URL" -f database/performance-indexes.sql

Run

pnpm dev

Open http://localhost:3000. Localhost development automatically enables the dev auth bypass unless you configure auth differently.

Configuration

Typical .env:

# Auth
MAGNOVA_AUTH_URL=https://auth.magnova.ai
COOKIE_SECRET=replace-with-a-long-random-secret
DEV_BYPASS_AUTH=true

# Database
DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require

# AI providers
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=
OPENROUTER_API_KEY=
GEMINI_API_KEY=

# Admin
ADMIN_SECRET_KEY=replace-with-admin-secret
[email protected]

See .env.example for all supported variables.

API

Graphini ships an OpenAPI 3 spec at api/openapi.yaml. It documents auth, chat, model settings, workspaces, documents, diagram generation, audio/upload conversion, collaborators, credits, admin operations, and MCP tool discovery.

Useful API groups:

Development

pnpm dev                    # Vite dev server
pnpm build                  # Production build
pnpm preview                # Preview production build
pnpm lint                   # Prettier + ESLint
pnpm lint:fix               # Format and autofix lint issues
pnpm test:unit              # Vitest
pnpm test:unit:coverage     # Vitest with coverage
pnpm test:e2e               # Playwright
pnpm test                   # Unit + E2E

The predev, prebuild, and prepreview hooks run scripts/build-aws-icon-pack.mjs so the icon pack is available to the app.

MermaidSeqBench

Graphini includes a benchmark harness for natural-language-to-Mermaid sequence diagrams:

pnpm bench:mermaid-seq -- --validate-dataset
OPENROUTER_API_KEY=... pnpm bench:mermaid-seq -- --limit 3
OPENROUTER_API_KEY=... pnpm bench:mermaid-seq -- --model openrouter:nvidia/nemotron-3-super-120b-a12b:free --judge-model openrouter:openai/gpt-oss-120b

Runs are written to tests/logs/mermaid-seq-bench/.

Project Structure

graphini/
├── api/                         # OpenAPI spec
├── database/                    # PostgreSQL schema and migrations
├── docs/                        # Project docs, security, code of conduct
├── scripts/                     # Icon-pack build and benchmark scripts
├── src/
│   ├── lib/
│   │   ├── components/          # Shared UI and shell components
│   │   ├── features/
│   │   │   ├── chat/            # AI chat UI and artifacts
│   │   │   ├── diagram/         # Mermaid rendering and diagram state
│   │   │   ├── editor/          # Desktop/mobile editor surfaces
│   │   │   ├── history/         # Diagram history utilities
│   │   │   └── icons/           # Icon metadata and lookup
│   │   ├── server/              # Auth, database, agents, chat, admin, rate limits
│   │   ├── stores/              # Svelte stores
│   │   └── util/                # Client/server helpers
│   └── routes/                  # SvelteKit pages and API routes
├── static/                      # Logo, screenshots, favicons, icon assets
├── tests/                       # Unit and Playwright tests
├── package.json
├── svelte.config.js
└── vite.config.js

Roadmap

• Natural-language Mermaid generation
• Workspace, canvas, edit, and view surfaces
• OpenAPI spec
• Multi-provider AI configuration
• PostgreSQL-backed persistence
• Magnova Auth integration and local dev auth
• Admin and model-lab surfaces
• MermaidSeqBench harness
• Realtime multi-user editing on one diagram
• Template gallery for architecture, onboarding, incidents, and CI/CD
• Deeper diagram diff and review workflow
• More cloud icon packs beyond AWS

Contributing

1. Fork the repo
2. Create a branch: git checkout -b feature/your-change
3. Run pnpm lint and the relevant tests
4. Open a pull request

See docs/CODE_OF_CONDUCT.md and docs/SECURITY.md.

Acknowledgments

• Cowork, for the collaboration/workspace lens behind Graphini
• Mermaid.js, for making diagrams-as-code practical
• Vercel AI SDK, for the provider-agnostic AI surface
• SvelteKit, for the app framework
• Drizzle ORM, for typed SQL ergonomics
• AWS Architecture Icons, for cloud diagram fidelity

License

MIT © Omkar Bhad