Skip to content

README.md

Latest commit

 

History

History
152 lines (119 loc) · 7.78 KB

README.md

File metadata and controls

152 lines (119 loc) · 7.78 KB

AstraDraw Documentation

This is the documentation index for AstraDraw, a self-hosted Excalidraw fork with enterprise features.

Quick Navigation for AI Agents

Use this decision tree to find relevant documentation:

If you need to... Read these docs
Understand the project Architecture
Set up development environment Development Guide
Test with sample data Test Users
Modify Excalidraw core (packages/) Fork Architecture
Refactor app-layer to use core Fork Refactoring Plan
Work on frontend UI/components Workspace UI Styling, State Management
Work on backend API Architecture, Roles & Teams
Fix navigation/routing bugs URL Routing, Scene Navigation
Fix scene loading issues CSS Hide/Show Fix
Implement a new feature Technical Debt (patterns), feature-specific plan
Work on comments Comment System Plan
Work on notifications Notification System Plan
Work on collaboration Collaboration, Auto-Collaboration
Deploy or configure Docker Docker Secrets, SSO Setup
Debug issues See Troubleshooting section

Documentation by Category

Getting Started

Document Description
DEVELOPMENT.md Development environment setup with hot-reload
TEST_USERS.md Test users, seed data, and permission scenarios
MVP_RELEASE_BUGS.md Bug tracking for MVP release with detailed postmortems
CONTRIBUTING.md Contribution guidelines and workflow

Note: frontend/packages/excalidraw/ is AstraDraw's controlled fork. You can modify any file in this directory - it's not an external dependency. See Architecture for details.

Architecture

Document Description
ARCHITECTURE.md System architecture, components, database schema
FORK_ARCHITECTURE.md Excalidraw fork ownership, when to modify core vs app layer
STATE_MANAGEMENT.md Jotai atoms, when to use useState vs atoms
URL_ROUTING.md URL patterns, navigation atoms, router utilities
SCENE_NAVIGATION.md Scene loading flow, CSS hide/show pattern

Features

Document Description
WORKSPACE.md Authentication, workspaces, scene management
COLLABORATION.md Real-time collaboration system
AUTO_COLLABORATION.md Auto-collaboration for shared collections
TALKTRACK.md Video recording feature
PRESENTATION_MODE.md Slideshow/presentation functionality
QUICK_SEARCH.md Quick search (Cmd+K) implementation
PENS_IMPLEMENTATION.md Custom pen presets
GIPHY_SUPPORT.md Stickers and GIFs integration
LIBRARIES_SYSTEM.md Shape library system
THUMBNAIL_PREVIEW.md Scene thumbnail generation
INVITE_LINKS.md Workspace invite links
WEB_EMBEDS.md Web embeds (SharePoint, Google Docs, Power BI, etc.)

Deployment

Document Description
DOCKER_SECRETS.md Docker secrets configuration
SSO_OIDC_SETUP.md OIDC/SSO authentication setup

Guides

Document Description
USER_PROFILE.md User profile management
WORKSPACE_UI_STYLING.md CSS patterns, dark mode, fonts
AUTOSAVE.md Auto-save implementation details
ROLES_TEAMS_COLLECTIONS.md Permission model, teams, collections

Troubleshooting

Document Description
CRITICAL_CSS_HIDE_SHOW_FIX.md Fix for scene data loss on navigation
SCENE_NAVIGATION_TESTS.md Navigation test scenarios
MAX_FILE_SIZE_ISSUE.md File size limit troubleshooting

Planning

Document Description
TECHNICAL_DEBT_AND_IMPROVEMENTS.md Technical debt analysis and established patterns
FORK_ARCHITECTURE_REFACTORING_PLAN.md Refactoring plan for leveraging Excalidraw fork (prop drilling, presentation actions, comment markers)
COMMENT_SYSTEM_IMPLEMENTATION_PLAN.md Comment system implementation (Phases 1-6 ✅, Phase 7 pending)
COMMENT_SYSTEM_RESEARCH.md Comment UI/UX research from Excalidraw Plus
NOTIFICATION_SYSTEM_IMPLEMENTATION_PLAN.md Notification system implementation (Phases 1-4, 6 complete)
NOTIFICATION_SYSTEM_RESEARCH.md Notification UI/UX research from Excalidraw Plus

Archive (Completed Plans)

Completed implementation plans are moved to docs/archive/ and excluded from AI indexing:

  • COLLABORATION_IMPLEMENTATION_PLAN.md - ✅ Complete (Dec 2025)
  • IMPLEMENTATION_PLANS.md - ✅ All 10 plans complete
  • SCENES_CACHE.md - ✅ React Query migration done
  • ROADMAP.md - Superseded by feature-specific plans

Key Commands

# Development (hot-reload)
just dev              # Start everything
just dev-status       # Check status
just dev-stop         # Stop everything

# Test Data
just db-seed          # Seed database with test users/data
just dev-fresh        # Fresh start (reset + seed + dev)

# Checks
just check            # Run all checks (frontend + backend + room)
just check-frontend   # TypeScript + Prettier + ESLint
just check-backend    # Build + Prettier + ESLint

# Docker
just up-local         # Start with local builds
just fresh-local      # Fresh start with local builds
just up               # Start with production images

Key File Locations

Purpose Path
Frontend entry frontend/excalidraw-app/App.tsx
Backend entry backend/src/main.ts
State atoms frontend/excalidraw-app/components/Settings/settingsState.ts
API client frontend/excalidraw-app/auth/api/ (modular structure)
URL router frontend/excalidraw-app/router.ts
Prisma schema backend/prisma/schema.prisma
Seed script backend/prisma/seed.ts
Docker config deploy/docker-compose.yml
Cursor rules .cursor/rules/ (folder format with RULE.md files)