{"id":31661272,"url":"https://github.com/acailic/archi-comm","last_synced_at":"2026-05-03T01:37:57.653Z","repository":{"id":313046677,"uuid":"1049813915","full_name":"acailic/archi-comm","owner":"acailic","description":"Desktop application  to practise system design","archived":false,"fork":false,"pushed_at":"2025-11-20T11:56:08.000Z","size":11137,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T01:37:30.517Z","etag":null,"topics":["interveiw-prep","interview","react","rust","system-design","tauri"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acailic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["acailic"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-09-03T14:30:50.000Z","updated_at":"2025-11-20T11:56:11.000Z","dependencies_parsed_at":"2025-09-03T16:41:02.079Z","dependency_job_id":"1568450d-9171-467c-9ca6-20d84fffeebb","html_url":"https://github.com/acailic/archi-comm","commit_stats":null,"previous_names":["acailic/archi-comm"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/acailic/archi-comm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Farchi-comm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Farchi-comm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Farchi-comm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Farchi-comm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acailic","download_url":"https://codeload.github.com/acailic/archi-comm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Farchi-comm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32555839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T00:31:16.350Z","status":"ssl_error","status_checked_at":"2026-05-03T00:31:15.546Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interveiw-prep","interview","react","rust","system-design","tauri"],"created_at":"2025-10-07T18:20:45.417Z","updated_at":"2026-05-03T01:37:57.643Z","avatar_url":"https://github.com/acailic.png","language":"TypeScript","funding_links":["https://github.com/sponsors/acailic"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"src-tauri/icons/128x128@2x.png\" width=\"110\" height=\"110\" alt=\"ArchiComm logo\"\u003e\n\n# ArchiComm Community Edition\n\n### A desktop companion for learning and practicing system design\n\n\u003c!-- Badges --\u003e\n\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/0000/badge)](https://www.bestpractices.dev/projects/0000)\n[![Build Status](https://github.com/acailic/archi-comm/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/acailic/archi-comm/actions/workflows/ci.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=acailic_archicomm\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=acailic_archicomm)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=acailic_archicomm\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=acailic_archicomm)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=acailic_archicomm\u0026metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=acailic_archicomm)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-0.2.1-blue.svg\"\u003e\n\u003cimg alt=\"Node \u003e=18\" src=\"https://img.shields.io/badge/node-%3E%3D18.0.0-339933?logo=nodedotjs\u0026logoColor=white\"\u003e\n\u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white\"\u003e\n\u003cimg alt=\"Prettier\" src=\"https://img.shields.io/badge/code_style-Prettier-ff69b4?logo=prettier\u0026logoColor=white\"\u003e\n\u003ca href=\"https://tauri.app\"\u003e\u003cimg alt=\"Tauri\" src=\"https://img.shields.io/badge/Desktop-Tauri-FFC131?logo=tauri\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003ca href=\"https://react.dev\"\u003e\u003cimg alt=\"React\" src=\"https://img.shields.io/badge/UI-React-61DAFB?logo=react\u0026logoColor=white\"\u003e\u003c/a\u003e\n\nLearn, practice, and teach system design fundamentals through guided scenarios, interactive diagrams, and repeatable exercises. This is the Community Edition, focused on core features for learners and interview practice. Upgrade to ArchiComm Pro for advanced features.\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Why ArchiComm Community Edition](#why-archicomm-community-edition)\n- [Study Flow](#study-flow)\n- [Community Edition Features](#community-edition-features)\n- [Delight Features](#delight-features-)\n- [Audio Features](#audio-features-community-edition)\n- [Study Modules](#study-modules)\n- [Canvas System Overview](#canvas-system-overview)\n- [System Design Practice Workflow](#system-design-practice-workflow)\n- [Tech Stack](#tech-stack)\n- [Architecture Guide](#architecture-guide)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [ArchiComm Pro](#archicomm-pro)\n- [License](#license)\n\n---\n\n## Why ArchiComm Community Edition\n\nArchiComm Community Edition is a free, open-source desktop app for learning and practicing system design. It focuses on core study flows and interview practice, making it ideal for students, job seekers, and educators.\n\n- Study by doing: work through realistic scenarios end-to-end\n- Reason about trade-offs: latency vs. throughput, consistency vs. availability, cost vs. performance\n- Build a reusable toolkit: patterns, checklists, estimations, and ADRs you can export\n- Teach and coach: run time-boxed interview sessions with rubrics and hints\n\nSee also: [src/docs/SystemDesignPractice.md](src/docs/SystemDesignPractice.md)\n\n---\n\n## Installation\n\n### Quick Install (macOS via Homebrew)\n\n```bash\nbrew tap acailic/tap\nbrew install --cask archicomm\n```\n\nThis installs the notarized desktop bundle to `/Applications/ArchiComm.app`. Launch it from Spotlight or run:\n\n```bash\nopen /Applications/ArchiComm.app\n```\n\nUpgrade anytime with `brew upgrade archicomm`. Prefer to build from source? Replace the cask command with `brew install acailic/tap/archicomm`.\n\n### Download from GitHub Releases\n\nEvery tagged build ships to [GitHub Releases](https://github.com/acailic/archi-comm/releases) with SHA256 checksums.\n\n| Platform                    | Artifact                    | How to install                                                      |\n| --------------------------- | --------------------------- | ------------------------------------------------------------------- |\n| macOS (Intel/Apple Silicon) | `ArchiComm-macOS.dmg`       | Double-click the DMG and drag ArchiComm to Applications.            |\n| Windows 10/11               | `ArchiComm-Setup-x64.exe`   | Run the signed installer and follow the wizard.                     |\n| Linux (AppImage)            | `ArchiComm-x86_64.AppImage` | `chmod +x ArchiComm-x86_64.AppImage \u0026\u0026 ./ArchiComm-x86_64.AppImage` |\n| Linux (Debian/Ubuntu)       | `archicomm_x.y.z_amd64.deb` | `sudo dpkg -i archicomm_x.y.z_amd64.deb`                            |\n\nDownload from the latest release manually or via curl:\n\n```bash\n# macOS DMG example\ncurl -L \\\n  https://github.com/acailic/archi-comm/releases/latest/download/ArchiComm-macOS.dmg \\\n  -o ArchiComm-macOS.dmg\n```\n\nVerify the downloaded file with the checksum listed on the release page (`shasum -a 256 \u003cfile\u003e` on macOS/Linux or `Get-FileHash` on Windows).\n\n### Development Setup\n\n```bash\n# Clone and launch the desktop app\ngit clone https://github.com/acailic/archicomm.git\ncd archicomm\nnpm install\nnpm run tauri:dev  # for desktop development\n# or\nnpm run dev        # for web development\n```\n\nBuild binaries: `npm run build` (creates signed Tauri bundles for your OS).\n\n### Package Manager\n\nWe standardize on npm for dependency management. Commit updates to `package-lock.json` and avoid adding alternative lockfiles (`yarn.lock`, `pnpm-lock.yaml`). Vite's canonical configuration lives at `config/vite.config.mjs`; update that file when changing dev server or build behavior.\n\n### Auto-Updates\n\nArchiComm includes an automatic update system that securely downloads and installs updates. You can:\n\n- Enable/disable automatic update checks in preferences\n- Manually check for updates from the Help menu\n- View update history and release notes\n\n---\n\n## Architecture Guide\n\nFor a deeper dive into the system and developer guidance, see the Architecture Guide.\n\n- Architecture overview, canvas internals, and performance: `docs/ARCHITECTURE.md`\n- Canvas drawing \u0026 annotation workflows: `docs/CANVAS_DRAWING_ANNOTATION_GUIDE.md`\n- APIs for components, hooks, and services: `docs/API_REFERENCE.md`\n- World-class canvas workflows and shortcuts: `docs/WORLD_CLASS_CANVAS_GUIDE.md`\n\n## Study Flow\n\n- Define requirements: functional scope, SLAs/SLOs, constraints, traffic assumptions.\n- Estimate: back‑of‑the‑envelope throughput, storage, QPS, fan‑out, costs.\n- Design: place components on the canvas; connect data flows and failure domains.\n- Explore trade‑offs: toggle replication, sharding, consistency, cache policies, queues.\n- Validate: run checklists and rubrics; capture risks and mitigation strategies.\n- Document: export diagram (SVG/PNG), notes/ADR (Markdown), and assumptions.\n\n---\n\n## Community Edition Features\n\n- **Voice Recording**: Record audio explanations of your system designs with manual transcript entry\n- 🎨 **Freehand Drawing**: Draw directly on the canvas with pen, highlighter, and eraser tools, plus keyboard shortcuts (`D`, `P`, `H`, `E`)\n- 💬 **Annotations**: Drop comments, notes, labels, arrows, and highlights with on-canvas guidance and quick placement overlays\n- ⌨️ **Canvas Shortcuts**: One-keystroke mode switching (`V` select, `D` draw, `A` annotate, `Esc` to exit) with in-app reference and toast feedback\n- Scenario templates: classic problems (URL shortener, news feed, chat, ride-hailing, file storage)\n- Patterns library: load balancing, caching, sharding, CQRS, pub/sub, rate limiting\n- Trade-off explorer: consistency levels, replication factors, partitioning schemes, backpressure\n- Estimation helpers: latency budgets, p50/p95, queue depth, storage growth, cost rough-order\n- Interview mode: time-boxed session, hints, rubric, and exportable scorecard\n\n## AI Canvas Assistant\n\nArchiComm’s canvas now speaks to modern coding models so you can sketch or refactor diagrams by describing your intent.\n\n- **Providers**: choose OpenAI (GPT‑4 family) or Anthropic Claude 3 under **Settings → AI**. API keys are encrypted locally and never leave the desktop app.\n- **Default provider**: pick your primary model via the “Provider Preference” selector. If that provider is unavailable, ArchiComm falls back to any other configured provider.\n- **Desktop first**: model calls run inside the Tauri shell to keep keys off the browser surface. The web build drops back to deterministic mock suggestions.\n- **Capabilities**: generate a diagram from scratch, add new services (“add a Redis cache between API and database”), or tidy an existing drawing (“group the background jobs into a worker tier”).\n- **Safety**: review warnings surfaced after each run—ambiguous instructions or unsupported actions (like annotations) are never applied silently.\n\n\u003e Tip: keep prompts precise. Include component names when updating existing nodes so the assistant can map aliases back to live canvas elements.\n\n- Exports: diagrams (SVG/PNG), notes (Markdown), and ADR templates\n\nNew in this build:\n\n- File-based custom challenges (import JSON via Challenge Selection \u003e Import Challenge)\n- Architecture templates pre-seeding (load suggested components and links)\n- Progressive solution hints (manual toggle or contextual prompts)\n- Auto-save of canvas to Tauri backend (diagram + connections)\n- Unified canvas mode switcher with floating drawing toolbar, mode indicator, and refreshed keyboard shortcuts\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePro Version Features (Upgrade)\u003c/b\u003e\u003c/summary\u003e\n\n- Automatic transcription (speech-to-text)\n- Advanced AI review and feedback\n- Company-specific templates and premium modules\n- Audio analysis and voice command features\n- Offline transcription and enhanced export options\n\n[Learn more about ArchiComm Pro](https://archicomm.com/pro)\n\n\u003c/details\u003e\n\n---\n\n## Delight Features ✨\n\nArchiComm includes thoughtful UI/UX enhancements designed to make learning system design more engaging and enjoyable:\n\n### Component Personality\n\n- **Hover Effects**: Components scale and glow subtly when you hover over them\n- **Drag Trails**: Semi-transparent trail effect follows components as you drag them\n- **Landing Animations**: Gentle bounce animation when dropping components on the canvas\n- **Connection Flows**: Animated data flow visualization along connection lines\n- **Selection Pulse**: Pulsing ring effect around selected components\n\n### Canvas Delight\n\n- **Empty States**: Beautiful, inspiring illustrations when the canvas is empty\n- **Grid Snap Feedback**: Satisfying magnetic pull animation when components snap to grid\n- **Smooth Zoom/Pan**: Momentum-based scrolling for natural canvas navigation\n- **First Component Celebration**: Special animation when adding your first component\n\n### Learning Tooltips\n\n- **Component Education**: Hover over components to see use cases, best practices, and real-world examples\n- **\"Did You Know?\" Facts**: Educational system design facts rotate during loading screens\n- **Pattern Library**: Browse and learn from common architecture patterns\n- **Contextual Help**: Smart tooltips appear based on your actions\n\n### Smooth Transitions\n\n- **Loading Skeletons**: Shimmer effect loading states with educational content\n- **Friendly Errors**: Helpful error messages with actionable suggestions instead of generic errors\n- **Beautiful Empty Panels**: Thoughtful empty states across all UI panels\n- **Micro-Interactions**: Polished animations for state changes and user actions\n\n### Configuration\n\nAll animations respect your system preferences and can be toggled:\n\n- **Animations Toggle**: Press `Ctrl+Shift+A` to toggle animations on/off\n- **Reduced Motion**: Automatically respects `prefers-reduced-motion` system setting\n- **Performance**: Animations use GPU acceleration and CSS for 60fps performance\n\n### Keyboard Shortcuts\n\n- `Shift+P` - Open pattern library\n- `Shift+?` - Show component education (when component selected)\n- `Ctrl+Shift+A` - Toggle animations\n- `Shift+D` - Show random system design fact\n- `Cmd+K` - Quick add component\n\n---\n\n## Audio Features (Community Edition)\n\nArchiComm Community Edition provides simple, reliable audio recording and manual transcription:\n\n### Recording\n\n- **MediaRecorder API**: Browser-native recording with pause/resume support\n- **Manual Transcription**: Rich text editor for typing your explanations\n- **Audio Playback**: Listen to your recordings while editing transcripts\n\n### Simplified Design\n\n- Single recording engine for maximum compatibility\n- No complex transcription dependencies\n- Manual transcript editing with word count and analysis\n- Export audio and transcript data together\n\n### Usage\n\n```typescript\nimport { SimpleAudioManager } from \"@audio/SimpleAudioManager\";\n\n// Initialize the simple audio manager\nconst audioManager = new SimpleAudioManager({\n  maxDuration: 300000, // 5 minutes\n});\n\n// Start recording\nawait audioManager.startRecording();\n\n// Stop and get audio data\naudioManager.stopRecording();\n// Audio data will be available via event listeners\n```\n\n---\n\n## Study Modules\n\nArchiComm Community Edition loads \"Tasks\" (study modules) that define prompts, acceptance criteria, hints, and assets. You can add your own tasks or use built-ins.\n\n- Structure and examples: [src/docs/SystemDesignPractice.md](src/docs/SystemDesignPractice.md)\n- Create a task: add a `task.json` under `src/lib/tasks/plugins/\u003cyour-task\u003e/` and export it from `src/lib/tasks/index.ts`\n\n---\n\n## Canvas System Overview\n\n- Simplified architecture: `DesignCanvas` integrates with `SimpleCanvas` (React Flow-based)\n- Simple state management: Zustand store (`SimpleAppStore`) replaces complex RxJS patterns\n- Component rendering: Single React Flow node type with customizable styling\n- Unified toolbar: Mode switcher toggles select/draw/annotate with contextual toolbars and mode indicator\n- Persistence: Local storage and export/import functionality\n\n### World-Class Canvas Features\n\nArchiComm is on a journey to become a **world-class, top 0.1% diagramming platform** for system design. The canvas includes advanced features that match or exceed industry leaders like Figma, Miro, and Excalidraw:\n\n#### Performance \u0026 Virtualization\n\n- **60 FPS Performance**: Sustained 60 FPS with 1000+ components using React Flow virtualization\n- **Adaptive Quality**: Automatic quality adjustments based on performance metrics\n- **Spatial Indexing**: RTree-based spatial indexing for O(log n) collision detection\n- **LOD Rendering**: Level-of-detail rendering reduces detail at low zoom levels\n\n#### Organization \u0026 Navigation\n\n- **Frames \u0026 Sections**: Figma-style frames for organizing components into logical groups\n- **Advanced Search**: Fuzzy search across components, connections, annotations, and frames with jump-to-result\n- **Navigation Breadcrumbs**: History tracking with back/forward navigation (Alt+Left/Right)\n- **Frame Hierarchy**: Nested frames with collapse/expand and visual hierarchy\n\n#### AI-Powered Features\n\n- **Text-to-Diagram**: Natural language to architecture diagram generation using LLMs\n- **Smart Suggestions**: Context-aware suggestions for connections, patterns, and anti-patterns\n- **Anti-Pattern Detection**: Automatic detection of common architecture anti-patterns\n- **Auto-Arrange**: Intelligent layout algorithms (by type, layer, flow, hierarchy)\n\n#### Precision \u0026 Routing\n\n- **Smart Routing**: Orthogonal and Manhattan routing with obstacle avoidance\n- **Connection Optimization**: Automatic anchor point selection for clean paths\n- **Grid Snap**: Magnetic snap-to-grid with visual feedback\n- **Alignment Guides**: Real-time alignment guides during drag operations\n\n#### Presentation \u0026 Export\n\n- **Presentation Mode**: Create slides from frames with transitions and speaker notes\n- **Template Library**: 50+ curated component templates organized by category\n- **Export Options**: High-res PNG/SVG export, PDF presentations, image sequences\n- **Frame Export**: Export individual frames as standalone images\n\n#### Keyboard Shortcuts (New)\n\n- `Ctrl+F`: Open canvas search\n- `Ctrl+G` / `Ctrl+Shift+G`: Navigate search results\n- `Ctrl+Shift+F`: Create frame from selection\n- `Alt+Left` / `Alt+Right`: Navigate back/forward\n- `Ctrl+Shift+I`: Toggle AI assistant panel\n- `Ctrl+Shift+T`: Open text-to-diagram\n- `Ctrl+Shift+P`: Enter presentation mode\n- `Ctrl+Shift+L`: Open template library\n- `Ctrl+2`: Zoom to fit selected components\n\nSee `CANVAS_WORLD_CLASS_ROADMAP.md` for the complete feature roadmap and implementation timeline.\n\n### Keyboard Shortcuts\n\n- `V`: Select mode / exit active mode\n- `D`: Drawing mode (defaults to the pen tool)\n- `A`: Annotation mode\n- `Esc`: Clear selection or exit the current mode\n- `H`: Pan tool (or highlighter when already drawing)\n- `Z`: Zoom tool\n- `Space` + drag: Pan viewport\n- `Ctrl/Cmd + A`: Select all; `Del`/`Backspace`: Delete\n- Arrow keys: Nudge; `Ctrl/Cmd` + arrow: Fine nudge\n\n### Drawing on Canvas\n\nArchiComm includes a powerful freehand drawing feature:\n\n1. Press `D` or click **Draw** in the unified toolbar.\n2. Use the floating drawing toolbar (anchored beneath the header) to select tools, colors, and stroke size.\n3. Move the cursor to preview stroke size, then click and drag to draw.\n4. Use undo/redo or the toolbar controls to manage strokes.\n5. Press `Esc` or `V`, or click the mode indicator ✕, to return to select mode.\n\n### Adding Annotations\n\n1. Press `A` or click **Annotate** to enable annotation mode.\n2. Pick an annotation type (comment, note, label, arrow, highlight) from the toolbar.\n3. Hover to view placement feedback, then click once to drop the annotation.\n4. Press `Enter` to edit, `Delete` to remove, and `Esc` or `V` to exit annotation mode.\n\nFor an in-depth guide (including troubleshooting and alternatives), see [docs/CANVAS_DRAWING_ANNOTATION_GUIDE.md](docs/CANVAS_DRAWING_ANNOTATION_GUIDE.md).\n\n### Task Plugins\n\n- Plugins live under `src/lib/task-system/plugins/\u003ctask-id\u003e`\n- Example: `url-shortener` with `task.json` and `assets/`\n- Loaded via `src/lib/task-system/templates/index.ts`\n\n### Developer Diagnostics\n\n- `DeveloperDiagnosticsPage` shows live canvas metrics (FPS, score, workers, memory)\n- Export diagnostics as JSON for debugging\n\n- Optional assets: diagrams, seed data, or reference links\n\nExample scenarios included:\n\n- URL shortener at scale\n- Twitter/Instagram news feed\n- Real-time chat and presence\n- Distributed cache and invalidation\n- Background jobs and retries\n- Ride-hailing dispatch\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePro Version Modules\u003c/b\u003e\u003c/summary\u003e\n\n- Company-specific templates\n- Premium scenario modules\n- Advanced challenge types\n\n[Upgrade to Pro](https://archicomm.com/pro)\n\n\u003c/details\u003e\n\n---\n\n## System Design Practice Workflow\n\n1. Select or import a challenge in Challenge Selection.\n2. Start designing on the canvas. Optionally load the architecture template when prompted.\n3. Toggle Solution Hints for progressive guidance. Hints group by topic and difficulty.\n4. Your work auto-saves to the local Tauri backend (no network required).\n5. Record your explanation, then review your session and export.\n\n### Importing Custom Challenges (File-Based)\n\n- Click Import Challenge in Challenge Selection (Tauri only).\n- Pick a `.json` file containing either an array of challenges or an object: `{ \"version\": \"...\", \"challenges\": [...] }`.\n- Valid entries must include: `id`, `title`, `description`, `requirements[]`, `difficulty`, `estimatedTime`, `category`.\n- Optional fields: `solutionHints[]`, `architectureTemplate`, `tags[]`, `prerequisites[]`, `learningObjectives[]`, `resources[]`, `variants[]`.\n\nMinimal JSON example:\n\n```\n{\n  \"version\": \"1.0.0\",\n  \"challenges\": [\n    {\n      \"id\": \"hello-world\",\n      \"title\": \"Hello World Service\",\n      \"description\": \"Design a tiny service that returns a greeting.\",\n      \"requirements\": [\"Expose HTTP endpoint\", \"Return greeting\"],\n      \"difficulty\": \"beginner\",\n      \"estimatedTime\": 10,\n      \"category\": \"system-design\",\n      \"solutionHints\": [\n        { \"id\": \"h1\", \"title\": \"API Shape\", \"content\": \"Keep it simple.\", \"type\": \"architecture\", \"difficulty\": \"beginner\" }\n      ],\n      \"architectureTemplate\": {\n        \"name\": \"Hello World\",\n        \"description\": \"API + Service\",\n        \"components\": [\n          { \"type\": \"api-gateway\", \"label\": \"API\", \"description\": \"HTTP entry\" },\n          { \"type\": \"server\", \"label\": \"Service\", \"description\": \"Business logic\" }\n        ],\n        \"connections\": [\n          { \"from\": \"API\", \"to\": \"Service\", \"label\": \"HTTP\", \"type\": \"sync\", \"protocol\": \"REST\" }\n        ]\n      }\n    }\n  ]\n}\n```\n\n### Templates and Hints\n\n- When a challenge contains an `architectureTemplate`, you’ll see a prompt to load it. You can also load it from the Solution Hints panel.\n- Hints appear in categories like architecture, scaling, technology, tradeoff, and optimization; toggle them anytime from the toolbar.\n\n### Persistence\n\n- The canvas auto-saves to the Tauri backend (in-memory for this build) keyed by challenge id.\n- Manual save triggers are available from the toolbar; exports (JSON/PNG) remain available.\n\n### Troubleshooting\n\n- Import fails: ensure your JSON matches the minimal format above. Invalid entries are ignored with warnings.\n- No auto-save: verify you’re running the Tauri desktop build. Web preview skips native persistence.\n- Template didn’t load: some components must have unique labels; the loader maps connections by label.\n\n## AI Review (Community Edition)\n\nYou can request basic rubric-based feedback using a local Tauri command that proxies to your model provider (keeps keys out of the UI). Setup steps and sample code are documented in [src/docs/SystemDesignPractice.md](src/docs/SystemDesignPractice.md).\n\n- Configure `OPENAI_API_KEY` (or swap in another provider)\n- Invoke `ai_review` from the UI; receive summary, strengths, risks, and a score\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePro Version AI Review\u003c/b\u003e\u003c/summary\u003e\n\n- Advanced AI feedback and scoring\n- Customizable rubrics\n- Company-specific review criteria\n\n[Upgrade to Pro](https://archicomm.com/pro)\n\n\u003c/details\u003e\n\n## Shortcuts\n\n- Command palette: `Ctrl/Cmd + K`\n- Add/Connect mode: `A` / `C`\n- Zoom to fit: `Ctrl/Cmd + 0`\n- Duplicate: `Ctrl/Cmd + D`\n- Undo/Redo: `Ctrl/Cmd + Z` / `Ctrl/Cmd + Shift + Z`\n\nPress `?` in the app for the full list.\n\n---\n\n## Tech Stack\n\n- Desktop shell: Tauri (Rust)\n- UI: React + TypeScript, Radix UI, Tailwind\n- Bundler/Dev: Vite\n- Testing: Vitest (unit/integration) + Playwright (E2E)\n- Demo assets: Automated marketing screenshots via Playwright (`npm run demo:prepare \u0026\u0026 npm run demo:screenshots`, see `e2e/README-DEMO-SCREENSHOTS.md`)\n- Canvas and interactions: React Flow canvas engine with custom overlays, `perfect-freehand` drawing, TipTap-powered annotations, Motion/Framer animations\n\n## Developer Tools\n\nArchiComm uses modern development tools to ensure code quality and consistency:\n\n- **Knip** — Detects unused files, dependencies, and exports (`npm run unused:check`)\n- **commitlint** — Enforces conventional commit message format\n- **Dependabot** — Automated dependency updates via GitHub\n- **EditorConfig** — Consistent editor settings across IDEs\n- **VS Code Integration** — Recommended extensions, debug configurations, and tasks\n- **Playwright CLI** — Install browsers with `npm run demo:prepare` (wraps `npx playwright install`) before running screenshot suites\n\n**Commit Format:** All commits must follow conventional commit format:\n\n```bash\nfeat(canvas): Add node auto-layout\nfix(audio): Resolve recording buffer overflow\ndocs: Update installation instructions\n```\n\n**Structure Validation:** Repository structure is validated on pre-commit:\n\n```bash\nnpm run validate:structure\n```\n\nFor complete tooling documentation, see `docs/TOOLING.md`.\n\n## Repository Layout\n\n- `config/` — centralised configuration for Vite, ESLint, Playwright, TypeScript, semantic-release, and Sonar\n- `docs/` — tracked documentation (essential docs in `docs/development/` are tracked; personal notes are git-ignored)\n- `src/packages/core/` (`@core`) — domain primitives, shared types, and core business logic\n- `src/packages/ui/` (`@ui`) — component library and design system primitives for the desktop app\n- `src/packages/canvas/` (`@canvas`) — diagram engine, interactions, and canvas-specific utilities\n- `src/packages/services/` (`@services`) — integration services, gateways, and persistence adapters\n- `src/packages/audio/` (`@audio`) — audio capture, processing, and transcription pipeline\n- `src/shared/hooks/`, `src/stores/`, `src/lib/` — shared hooks, Zustand stores, and utilities that complement the packages\n- `distribution/homebrew/` — Homebrew cask \u0026 formula definitions tracked with the repo\n- `tools/` — development scripts and structure validators (`npm run validate:structure`)\n\nUseful scripts:\n\n- `npm run dev` — web dev server (Vite)\n- `npm run tauri:dev` — desktop dev shell\n- `npm run test:coverage` — generate coverage report\n- `npm run e2e` — run Playwright tests locally\n- `npm run validate:structure` — validate repository structure\n- `npm run deps:check` — check for outdated dependencies\n- `npm run unused:check` — detect unused code and dependencies\n\nFor complete tooling documentation, see `docs/TOOLING.md`.\n\n---\n\n## Contributing\n\nWe welcome improvements to modules, patterns, checklists, and study flows for the Community Edition.\n\n- Start here: `CONTRIBUTING.md` for a quick start checklist, local dev workflow, and PR standards\n- Explore the architecture: `docs/ARCHITECTURE.md`\n- Consult the API reference: `docs/API_REFERENCE.md`\n- Development tooling: `docs/TOOLING.md` for all tools and their usage\n- Security policy: `docs/SECURITY.md`\n- API stability: `docs/API_STABILITY.md`\n- Maintainers: `docs/MAINTAINERS.md`\n\nIdeas that help learners most:\n\n- New study modules with clear acceptance criteria and hints\n- Trade-off explorers (e.g., sharding vs. hashing strategies)\n- Estimation worksheets and rubric improvements\n- Better exports (ADR templates, interview scorecards)\n- Audio and speech-to-text enhancements (see `TODO.md`)\n\n---\n\n## ArchiComm Pro\n\nArchiComm Pro unlocks advanced features for professional users, including automatic transcription, advanced AI review, company-specific templates, and more. Upgrade for the full experience.\n\n[Learn more and upgrade](https://archicomm.com/pro)\n\n---\n\n## Troubleshooting\n\n### Drawing Issues\n\n**Can't draw on the canvas?**\n\n- Press `D` or click **Draw** in the unified toolbar to enter drawing mode.\n- Pick a pen, highlighter, or eraser in the floating toolbar beneath the header.\n- Confirm the mode indicator badge shows _Drawing Mode_ and the cursor preview circle is visible.\n- If strokes still do not appear, press `V` then `D` to reset the mode and ensure you are dragging on the canvas (not over other panels).\n\n### Annotation Issues\n\n**Annotations not placing?**\n\n- Press `A` or click **Annotate**, then choose a comment, note, label, arrow, or highlight tool.\n- Look for the hover halo that appears when the cursor is ready to place an annotation.\n- Ensure no side panels or overlays are covering the canvas—toggle layer visibility if necessary.\n- Press `Esc` or `V`, then re-enter annotation mode with `A` to reset the workflow.\n\nSee [docs/CANVAS_DRAWING_ANNOTATION_GUIDE.md](docs/CANVAS_DRAWING_ANNOTATION_GUIDE.md) for detailed troubleshooting, best practices, and library alternatives.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by the ArchiComm Team**\n\n_Empowering architects to design the future, one component at a time._\n\n⭐ **Star us on GitHub** • 🐦 **Follow on Twitter** • 💬 **Join Discord**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facailic%2Farchi-comm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facailic%2Farchi-comm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facailic%2Farchi-comm/lists"}