ExcaliDash/AGENTS.md

ExcaliDash Developer Guide

What is ExcaliDash?

ExcaliDash is a full-stack dashboard application for managing and organizing Excalidraw drawings. It provides a interface for creating, organizing, and collaborating on diagrams with features like collections, real-time collaboration, file import/export, and bulk operations.

Project Overview

Core Features

• Drawing Management: Create, edit, and organize Excalidraw drawings
• Collections: Organize drawings into folders/categories
• Real-time Collaboration: Multiple users can edit drawings simultaneously
• Import/Export: Support for .excalidraw and .json file formats
• Bulk Operations: Multi-select drawings for delete, duplicate, and move operations
• Search & Sort: Find drawings by name with sorting by name, created date, or modified date
• Trash System: Soft delete with permanent delete option
• Drag & Drop: Intuitive file dragging and drawing reordering
• Dark/Light Theme: Automatic theme detection with manual toggle

Tech Stack

Frontend:

• React 18 + TypeScript
• Vite (build tool)
• Tailwind CSS (styling)
• Excalidraw (drawing canvas)
• Socket.io Client (real-time features)
• React Router (navigation)
• Lucide React (icons)

Backend:

• Node.js + Express
• TypeScript
• Prisma ORM
• SQLite database
• Socket.io (real-time server)

Infrastructure:

• Docker (containerization)
• Docker Compose (multi-container orchestration)

Project Structure

ExcaliDash/
├── README.md                 # Project overview
├── AGENTS.md                 # This file - developer guide
├── DOCKER.md                 # Docker documentation
├── .gitignore               # Git ignore rules
├── .dockerignore            # Docker ignore rules
├── docker-compose.yml       # Production Docker setup
├── docker-compose.prod.yml  # Additional production config
├── publish-docker.sh        # Docker deployment script
│
├── backend/                 # Node.js/Express backend
│   ├── src/
│   │   ├── index.ts         # Main server file
│   │   └── generated/       # Prisma generated client
│   ├── prisma/
│   │   ├── schema.prisma    # Database schema
│   │   ├── migrations/      # Database migrations
│   │   └── dev.db          # SQLite database (development)
│   ├── package.json         # Backend dependencies
│   ├── Dockerfile          # Backend container config
│   ├── .env.example        # Environment variables template
│   └── docker-entrypoint.sh # Container startup script
│
└── frontend/               # React frontend application
    ├── src/
    │   ├── components/     # Reusable UI components
    │   ├── pages/         # Route components
    │   ├── hooks/         # Custom React hooks
    │   ├── context/       # React context providers
    │   ├── types/         # TypeScript type definitions
    │   ├── utils/         # Utility functions
    │   ├── api/           # API client functions
    │   └── assets/        # Static assets
    ├── public/            # Public assets
    ├── package.json       # Frontend dependencies
    ├── Dockerfile         # Frontend container config
    ├── vite.config.ts     # Vite configuration
    ├── tailwind.config.js # Tailwind CSS configuration
    └── nginx.conf         # Nginx configuration for production

Getting Started

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose (for containerized development)
• Git

Development Setup

Option 1: Local Development (Recommended)

1. Install Backend Dependencies

   cd backend
   npm install
   

2. Install Frontend Dependencies

   cd ../frontend
   npm install
   

3. Setup Environment Variables

   cd ../backend
   cp .env.example .env
   # Edit .env if needed
   

4. Initialize Database

   npx prisma generate
   npx prisma db push
   

5. Start Backend Development Server

   cd backend
   npm run dev
   # Server runs on http://localhost:8000
   

6. Start Frontend Development Server (in a new terminal)

   cd frontend
   npm run dev
   # Frontend runs on http://localhost:5173
   

Environment Variables

Backend (.env):

DATABASE_URL="file:./prisma/dev.db"
PORT=8000
NODE_ENV=development

Frontend (.env.example):

VITE_API_URL=http://localhost:8000

Making Changes

Development Workflow

1. Create a Feature Branch

   git checkout -b feature/your-feature-name
   

2. Make Your Changes

   • Follow the existing code style and patterns
   • Add TypeScript types for new features
   • Update database schema if needed (see Database section)

3. Test Your Changes

   • Test both locally and with Docker
   • Check that existing functionality still works

4. Commit and Push

   git add .
   git commit -m "feat: add your feature description"
   git push origin feature/your-feature-name
   

Code Style and Standards

• TypeScript: Use strict TypeScript typing
• Component Structure: Follow the existing component patterns in frontend/src/components/
• API Design: RESTful endpoints in backend/src/index.ts
• Database: Use Prisma migrations for schema changes
• Styling: Tailwind CSS classes with the existing design system

File Organization Guidelines

• Frontend Components: Keep related components together
• Custom Hooks: Place in frontend/src/hooks/
• Utilities: Place in frontend/src/utils/
• API Routes: Add to backend/src/index.ts
• Database Models: Update backend/prisma/schema.prisma

Database

Schema Overview

The application uses two main models:

Collection:

• id (String, UUID) - Primary key
• name (String) - Collection name
• drawings (Relation) - Related drawings
• createdAt, updatedAt (DateTime) - Timestamps

Drawing:

• id (String, UUID) - Primary key
• name (String) - Drawing name
• elements (String, JSON) - Excalidraw elements
• appState (String, JSON) - Excalidraw application state
• files (String, JSON) - Associated files
• preview (String, SVG) - Thumbnail preview
• version (Int) - Version number for conflict detection
• collectionId (String, nullable) - Foreign key to Collection
• createdAt, updatedAt (DateTime) - Timestamps

Making Database Changes

1. Modify the Schema Edit backend/prisma/schema.prisma

2. Create a Migration

   cd backend
   npx prisma migrate dev --name your_migration_name
   

3. Update TypeScript Types

   npx prisma generate
   

4. Test the Changes

   npx prisma db push  # Apply to development database
   

Database Commands

# Generate Prisma client
npx prisma generate

# Create and apply migration
npx prisma migrate dev --name migration_name

# Reset database (development only)
npx prisma migrate reset

# View database in Prisma Studio
npx prisma studio

# Deploy migrations to production
npx prisma migrate deploy

API Documentation

Base URL

• Development: http://localhost:8000
• Production: Configured via environment variables

Endpoints

Drawings

• GET /drawings - List drawings (supports search and collection filtering)
• GET /drawings/:id - Get single drawing
• POST /drawings - Create new drawing
• PUT /drawings/:id - Update drawing
• DELETE /drawings/:id - Delete drawing permanently
• POST /drawings/:id/duplicate - Duplicate drawing

Collections

• GET /collections - List all collections
• POST /collections - Create new collection
• PUT /collections/:id - Update collection
• DELETE /collections/:id - Delete collection (moves drawings to unorganized)

System

• GET /health - Health check endpoint

Real-time Events (Socket.io)

Client → Server

• join-room - Join drawing room for collaboration
• cursor-move - Broadcast cursor position
• element-update - Broadcast drawing changes
• user-activity - Update user active status

Server → Client

• presence-update - User presence in room
• cursor-move - Other user's cursor position
• element-update - Other user's drawing changes

Environment Setup

Production Environment Variables:

• DATABASE_URL - SQLite database path
• PORT - Backend server port
• NODE_ENV - Set to "production"

Troubleshooting

Common Issues

1. Database Connection Error

   • Check that the database file exists in backend/prisma/dev.db
   • Ensure proper permissions on the database file
   • Verify DATABASE_URL in .env

2. Prisma Client Issues

   • Run npx prisma generate to regenerate client
   • Clear node_modules and reinstall dependencies

3. Port Already in Use

   • Change PORT in backend/.env
   • Update frontend API URL accordingly

4. Docker Build Failures

   • Check Dockerfile syntax
   • Ensure all dependencies are listed in package.json
   • Verify build context in docker-compose.yml

5. Frontend Not Loading

   • Check browser console for errors
   • Verify API_URL in frontend environment
   • Check network connectivity to backend

Architecture Details

Frontend Architecture

The frontend follows a component-based architecture with:

• Pages: Route-level components (src/pages/)
• Components: Reusable UI components (src/components/)
• Hooks: Custom React hooks for state management (src/hooks/)
• Context: Global state providers (src/context/)
• Utils: Utility functions (src/utils/)

Key patterns:

• State management using React hooks and context
• API calls centralized in src/api/
• TypeScript for type safety throughout
• Tailwind CSS for styling with custom design tokens

Backend Architecture

The backend follows a traditional MVC pattern:

• Routes: API endpoints in src/index.ts
• Models: Prisma schema definitions
• Services: Business logic (can be extracted to separate files)
• Middleware: CORS, JSON parsing, etc.

Real-time features:

• Socket.io for WebSocket connections
• Room-based collaboration
• Presence tracking
• Cursor position broadcasting

Data Flow

1. Drawing Creation: Frontend → API → Database
2. Real-time Updates: Frontend → Socket.io → Other Frontends
3. Data Persistence: Regular API calls for saving state
4. File Management: Frontend → API → Database (as JSON)

Contributing

Pull Request Process

1. Ensure all tests pass
2. Update documentation if needed
3. Add commit messages following conventional commits
4. Request review from maintainers

Commit Message Format

type(scope): description

feat(auth): add user authentication
fix(editor): resolve drawing save issue
docs(api): update endpoint documentation

Types: feat, fix, docs, style, refactor, test, chore

Resources

• Excalidraw Documentation
• Prisma Documentation
• React Documentation
• Socket.io Documentation
• Tailwind CSS Documentation
• Vite Documentation

This documentation is maintained alongside the codebase. Please update it when making significant architectural changes.