# genaiwithshubham/opennapkinai architecture

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

- Interactive diagram: https://gitdiagram.com/genaiwithshubham/opennapkinai
- Repository: https://github.com/genaiwithshubham/opennapkinai

## Overview

##### Project type and purpose
- This is a full-stack, monorepo web application (“OpenNapkinAI”) for converting user text into hand-drawn-style visuals.
- Frontend: React + Tailwind + Vite + EditorJS + RoughJS
- Backend: Express.js providing REST endpoints for AI integration and note management
- AI models: local Ollama or Anthropic Claude via Vercel AI SDK
- Shared code/config: TypeScript types, ESLint rules, tsconfig presets

##### File structure
- Top-level “apps” directory holds two apps:
- apps/backend – Express server with src/app.ts, src/routes/{ai.ts, notes.ts}, src/data/notes.ts
- “packages” directory holds reusable modules:
- types – shared TypeScript definitions (e.g. Note)
- eslint-config – centralized lint rules
- typescript-config – JSON presets for Node/Vite/React
- Turborepo configuration (turbo.json, .turbo/) orchestrates builds, caching, and parallel tasks

##### README for additional insights
- Key features: text-to-visual generation, CRUD for notes, choice of AI backends, hand-drawn style
- No external database: notes are stored via a lightweight data layer (in-memory or file)
- Env-based AI configuration (ANTHROPIC_API_KEY, OLLAMA_HOST, etc.)

##### Main components and their relationships
a. Frontend Web Client
- UI components (Editor, DiagramContainer, NoteCard, pages)
- Custom React hooks (useNoteQuery, useCreateNoteMutation, useNotesQuery, etc.)
- Renders AI response with RoughJS via DiagramRenderer
b. Backend API Server
- Express app with two route groups:
- /routes/notes.ts – CRUD operations using src/data/notes.ts
- /routes/ai.ts – Orchestrates AI calls (local Ollama or Anthropic)
- Middleware, error handling, environment configuration
c. AI Model Services (External)
- Ollama local host or Anthropic remote service
d. Shared Packages
- eslint-config & typescript-config: maintain coding standards and TS compiler settings
e. Scripts & Build Tools
- Python scripts for theme-building or converting sketches
- Turborepo to coordinate build/test across all modules

##### Important architectural patterns and principles
- Monorepo structure (Turborepo) for code sharing and unified CI/CD
- Clear separation of concerns (UI vs. API vs. AI integration vs. shared types)
- Component-based UI with custom hooks for data fetching
- Route-based modular backend
- Environment-driven configuration for pluggable AI providers
- Shared TypeScript definitions to avoid drift

##### Key details not to miss
- Monorepo orchestration (Turborepo caching/build tasks) at the top level
- Shared TypeScript types enforcing contract between frontend and backend
- Pluggable AI provider layer abstracted in routes/ai.ts

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "OpenNapkinAI Monorepo"
        direction TB

        subgraph "Frontend (React/Vite)"
            direction TB
            Editor["Editor"]:::frontend
            DiagramContainer["DiagramContainer"]:::frontend
            DiagramRenderer["DiagramRenderer"]:::frontend
            NoteCard["NoteCard"]:::frontend
            NoteEditorPage["NoteEditorPage"]:::frontend
            NotesPage["NotesPage"]:::frontend

            useNoteQuery["useNoteQuery"]:::frontend
            useNotesQuery["useNotesQuery"]:::frontend
            useCreateNoteMutation["useCreateNoteMutation"]:::frontend
            useUpdateNoteMutation["useUpdateNoteMutation"]:::frontend
            useDeleteNoteMutation["useDeleteNoteMutation"]:::frontend

            APIClient["api.ts (Data Layer)"]:::frontend
            DiagramsData["diagrams.ts"]:::frontend
            ColorsData["colors.ts"]:::frontend
            RoutesFile["routes.tsx"]:::frontend
            SchemaFile["schema.ts"]:::frontend

            Editor --> DiagramContainer
            DiagramContainer --> DiagramRenderer
            DiagramRenderer --> DiagramsData
            DiagramRenderer --> ColorsData

            NoteEditorPage --> Editor
            NotesPage --> NoteCard

            NoteEditorPage --> useNoteQuery
            NotesPage --> useNotesQuery
            NoteEditorPage --> useCreateNoteMutation
            NoteEditorPage --> useUpdateNoteMutation
            NotesPage --> useDeleteNoteMutation

            useNoteQuery --> APIClient
            useNotesQuery --> APIClient
            useCreateNoteMutation --> APIClient
            useUpdateNoteMutation --> APIClient
            useDeleteNoteMutation --> APIClient

            APIClient -->|"HTTP/REST (JSON)"| NotesRoute
            APIClient -->|"HTTP/REST (JSON)"| AIRoute

        end

        subgraph "Backend (Express)"
            direction TB
            AppEntry["app.ts"]:::backend
            ServerBootstrap["index.ts"]:::backend
            NotesRoute["notes.ts"]:::backend
            AIRoute["ai.ts"]:::backend
            NotesData["notes.ts (data)"]:::backend
            ESLintBackend[".eslintrc.cjs"]:::backend
            TSConfigBackend["tsconfig.json"]:::backend

            AppEntry --> NotesRoute
            AppEntry --> AIRoute
            NotesRoute --> NotesData
            AIRoute -->|Chooses provider| Ollama
            AIRoute -->|Chooses provider| Anthropic
        end

        subgraph "Shared Packages"
            direction TB
            TypesIndex["types/src/index.ts"]:::shared
            TypesNote["types/src/note.ts"]:::shared
            ESLintConfig["eslint-config/index.js"]:::shared
            TSConfigBase["typescript-config/base.json"]:::shared
            TSConfigNode["typescript-config/node.json"]:::shared
            TSConfigReactLib["typescript-config/react-library.json"]:::shared
            TSConfigVite["typescript-config/vite.json"]:::shared

            TypesIndex --> TypesNote
        end

        subgraph "Scripts & Tooling"
            direction TB
            DiagramTemplates["scripts/diagrams/*.xml"]:::tooling
            RoughConverter["roughjs-convertor.py"]:::tooling
            ThemeBuilder["theme-builder.py"]:::tooling
            OutputArtifact["output.json"]:::tooling
            DiagramTemplates --> RoughConverter
            ThemeBuilder --> OutputArtifact
        end

        subgraph "Monorepo Orchestration"
            direction TB
            TurboConfig["turbo.json"]:::tooling
            TurboCache[".turbo/"]:::tooling
        end

    end

    Ollama["Ollama (Local)"]:::external
    Anthropic["Anthropic (Remote)"]:::external

    classDef frontend fill:#D6E4FF,stroke:#1E3A8A,stroke-width:1px
    classDef backend fill:#D1FAE5,stroke:#047857,stroke-width:1px
    classDef shared fill:#F3F4F6,stroke:#6B7280,stroke-width:1px
    classDef external fill:#FEF3C7,stroke:#B45309,stroke-width:1px
    classDef tooling fill:#F5E1FF,stroke:#8B5CF6,stroke-width:1px

    click Editor "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/components/Editor.tsx"
    click DiagramContainer "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/components/DiagramContainer.tsx"
    click DiagramRenderer "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/components/DiagramRenderer.tsx"
    click NoteCard "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/components/NoteCard.tsx"
    click NoteEditorPage "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/components/pages/NoteEditorPage.tsx"
    click NotesPage "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/components/pages/NotesPage.tsx"
    click useNoteQuery "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/hooks/useNoteQuery.ts"
    click useNotesQuery "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/hooks/useNotesQuery.ts"
    click useCreateNoteMutation "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/hooks/useCreateNoteMutation.ts"
    click useUpdateNoteMutation "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/hooks/useUpdateNoteMutation.ts"
    click useDeleteNoteMutation "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/hooks/useDeleteNoteMutation.ts"
    click APIClient "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/data/api.ts"
    click DiagramsData "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/data/diagrams.ts"
    click ColorsData "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/data/colors.ts"
    click RoutesFile "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/routes.tsx"
    click SchemaFile "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/frontend/src/schema.ts"

    click AppEntry "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/src/app.ts"
    click ServerBootstrap "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/src/index.ts"
    click NotesRoute "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/src/routes/notes.ts"
    click AIRoute "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/src/routes/ai.ts"
    click NotesData "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/src/data/notes.ts"
    click ESLintBackend "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/.eslintrc.cjs"
    click TSConfigBackend "https://github.com/genaiwithshubham/opennapkinai/blob/main/apps/backend/tsconfig.json"

    click TypesIndex "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/types/src/index.ts"
    click TypesNote "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/types/src/note.ts"
    click ESLintConfig "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/eslint-config/index.js"
    click TSConfigBase "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/typescript-config/base.json"
    click TSConfigNode "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/typescript-config/node.json"
    click TSConfigReactLib "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/typescript-config/react-library.json"
    click TSConfigVite "https://github.com/genaiwithshubham/opennapkinai/blob/main/packages/typescript-config/vite.json"

    click DiagramTemplates "https://github.com/genaiwithshubham/opennapkinai/tree/main/scripts/diagrams/"
    click RoughConverter "https://github.com/genaiwithshubham/opennapkinai/blob/main/scripts/roughjs-convertor.py"
    click ThemeBuilder "https://github.com/genaiwithshubham/opennapkinai/blob/main/scripts/theme-builder.py"
    click OutputArtifact "https://github.com/genaiwithshubham/opennapkinai/blob/main/scripts/output.json"
    click TurboConfig "https://github.com/genaiwithshubham/opennapkinai/blob/main/turbo.json"
    click TurboCache "https://github.com/genaiwithshubham/opennapkinai/tree/main/.turbo/"
```
