|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is **ZenUML Web Sequence**, a free sequence diagram online tool that converts text into UML sequence diagrams. It's built as both a web application (https://app.zenuml.com) and a Chrome extension. |
| 8 | + |
| 9 | +## Technology Stack |
| 10 | + |
| 11 | +- **Frontend Framework**: Preact (v10.18.1) - lightweight React alternative |
| 12 | +- **Build Tool**: Vite (v6.3.5) |
| 13 | +- **UI Libraries**: Tailwind CSS, Radix UI, Headless UI |
| 14 | +- **Core Engine**: @zenuml/core (v3.32.3) - sequence diagram rendering |
| 15 | +- **Code Editor**: CodeMirror (v5.65.16) |
| 16 | +- **Backend**: Firebase (authentication, Firestore, cloud functions) |
| 17 | +- **Testing**: Jest with Enzyme |
| 18 | +- **Package Manager**: Yarn (required - see volta config) |
| 19 | + |
| 20 | +## Architecture |
| 21 | + |
| 22 | +The application follows a component-based architecture with: |
| 23 | +- **Split-pane interface**: Code editor on left, live preview on right |
| 24 | +- **Modal-based UI**: Settings, help, pricing, etc. |
| 25 | +- **Service layer pattern**: Business logic separated in `/src/services/` |
| 26 | +- **Multi-page support**: Users can create multiple diagram pages |
| 27 | +- **Chrome extension support**: Packaged separately in `/extension/` |
| 28 | + |
| 29 | +Key directories: |
| 30 | +- `/src/components/` - Preact components |
| 31 | +- `/src/services/` - Business logic and Firebase integration |
| 32 | +- `/src/zenuml/` - ZenUML specific components |
| 33 | +- `/functions/` - Firebase cloud functions |
| 34 | + |
| 35 | +## Common Development Commands |
| 36 | + |
| 37 | +```bash |
| 38 | +# Install dependencies (use yarn, not npm) |
| 39 | +yarn install |
| 40 | + |
| 41 | +# Start development server |
| 42 | +yarn dev |
| 43 | + |
| 44 | +# Build for production |
| 45 | +yarn build |
| 46 | + |
| 47 | +# Package for release (creates extension.zip) |
| 48 | +yarn release |
| 49 | + |
| 50 | +# Run tests |
| 51 | +yarn test |
| 52 | + |
| 53 | +# Run linting |
| 54 | +yarn lint |
| 55 | + |
| 56 | +# Deploy to staging |
| 57 | +yarn deploy:staging |
| 58 | + |
| 59 | +# Deploy to production |
| 60 | +yarn deploy:prod |
| 61 | +``` |
| 62 | + |
| 63 | +## Testing |
| 64 | + |
| 65 | +```bash |
| 66 | +# Run all unit tests |
| 67 | +yarn test |
| 68 | + |
| 69 | +# Run a specific test file |
| 70 | +yarn test src/common/ensure.test.js |
| 71 | + |
| 72 | +# Manual testing guide available at |
| 73 | +# src/manual-test-guide.md |
| 74 | +``` |
| 75 | + |
| 76 | +Test files follow the pattern `*.test.js` and are located either in `/src/tests/` or alongside the components they test. |
| 77 | + |
| 78 | +## Important Development Notes |
| 79 | + |
| 80 | +1. **Always use Yarn**, not npm - the project uses Yarn workspaces and volta for version management |
| 81 | +2. **Preact aliases**: React imports are aliased to Preact in the build config |
| 82 | +3. **No TypeScript**: This is a JavaScript project with JSX |
| 83 | +4. **Firebase emulators**: Use for local development - see `/docs/firebase-emulator-testing.md` |
| 84 | +5. **Pre-commit hooks**: Automatically run Prettier and ESLint |
| 85 | +6. **Chrome extension**: Built to `/extension/` directory during release |
| 86 | + |
| 87 | +## Code Style |
| 88 | + |
| 89 | +- ESLint configuration extends `eslint-config-synacor` |
| 90 | +- Prettier formatting on commit via lint-staged |
| 91 | +- Follow existing patterns for component structure and service layer |
| 92 | + |
| 93 | +## Deployment Process |
| 94 | + |
| 95 | +- **Preview**: Created automatically for PRs |
| 96 | +- **Staging**: Merges to master deploy to https://staging.zenuml.com |
| 97 | +- **Production**: Create tag `release-<version>` to deploy to https://app.zenuml.com |
| 98 | + |
| 99 | +## Key Features to Understand |
| 100 | + |
| 101 | +1. **Diagram Syntax**: Uses @zenuml/core for parsing and rendering |
| 102 | +2. **Multi-page System**: Users can create/delete multiple diagram pages |
| 103 | +3. **Cloud Sync**: Firebase integration for saving diagrams |
| 104 | +4. **Offline Support**: Works without internet connection |
| 105 | +5. **Export Options**: PNG, SVG, and other formats |
| 106 | +6. **Subscription System**: Paddle integration for premium features |
| 107 | +7. **Theme Support**: Multiple editor themes and diagram styles |
| 108 | + |
| 109 | +## Cursor Rules Integration |
| 110 | + |
| 111 | +This project has Cursor rules configured at `.cursor/rules/interactive-feedback-mcp.mdc` that enable interactive feedback through MCP when working with the codebase. |
0 commit comments