# I'll explore the codebase systematically to understand the project structure and technology stack.
**Session ID:** `ea9dca43-8878-45f9-bc53-1cf5b9ae5176` **Project:** /Users/rdmtv/Documents/claydev-local/macos-apps-v2/vscode-specstory **Date:** 2025-12-11T06:54:38.716Z **Slug:** zippy-baking-acorn

---

## Conversation I'll explore the codebase systematically to understand the project structure and technology stack. Let me read the key configuration files: Now let me explore the source directory structure and examine the app directories: Let me continue exploring and also check for test files: Let me explore the main directories more thoroughly: Let me read some key files to understand the architecture better: Now let me check some schema files to understand the data model: Let me check for test/spec files and any build output: Let me check the drizzle config files and README: Now let me check the library files to understand more of the architecture: Let me check one of the schema files and look at routes to understand the API better: Perfect! Let me get a few more details about the middleware and check for any testing infrastructure: Now let me check the migration files and overall structure summary: Let me check the correct migration file name and get a final summary: Perfect! Now I have a comprehensive understanding of the project. Let me create a detailed summary report. ## Comprehensive Project Analysis: vscode-specstory ### 1. Project Type & Purpose **Type**: Node.js / TypeScript backend service for data persistence and API layer **Purpose**: SpecStory is a local-first AI conversation capture and indexing system that serves as a backend database and REST API for the SpecStory ecosystem. It preserves, searches, and organizes AI coding interactions from various tools (Claude Code, Cursor, Copilot, etc.) into persistent, searchable documentation. **Architecture Philosophy**: "Intent is the new source code" - converting ephemeral chat sessions into permanent, indexed knowledge. ### 2. Technology Stack **Core Framework & Runtime**: - **Runtime**: Bun (JavaScript runtime - see `bun.ts`) - **Framework**: Hono v4.10.8 (lightweight web framework) - **Language**: TypeScript 5.7.2 - **Module System**: ES modules (ESNext) **Database & ORM**: - **Database**: SQLite (multiple databases managed) - **ORM**: Drizzle ORM v0.39.3 (with TypeScript support) - **Migration Tool**: Drizzle-kit v0.30.1 - **SQLite Driver**: better-sqlite3 v11.7.0 (native bindings for Node/Bun) **Validation & Utilities**: - **Validation**: Zod v4.1.13 (TypeScript-first schema validation) - **CLI Framework**: Commander v14.0.2 (command-line interfaces) - **Logging**: Built custom logger (app/lib/logger.ts) - **Progress/Output**: ora v9.0.0 (spinners/progress bars), cli-table3 v0.6.5 (tables), chalk v5.6.2 (colored output) **Build & Development**: - **TypeScript Compiler**: tsc (for compilation) - **Build Tool**: esbuild (via tsx) - **Task Runner**: npm/bun scripts in package.json ### 3. Project Structure ``` vscode-specstory/ ├── package.json # Main package configuration ├── tsconfig.json # TypeScript configuration ├── bun.ts # Bun server entry point ├── drizzle-*.config.ts # Database migration configs (3 databases) │ ├── app/ # Main application code │ ├── api/ # REST API (Hono) │ │ ├── server.ts # Hono app setup with routes │ │ ├── middleware/ # Global middleware │ │ │ ├── error-handler.ts │ │ │ ├── db-context.ts # DB context injection │ │ │ ├── request-logger.ts │ │ │ └── index.ts │ │ ├── routes/ # API endpoints │ │ │ ├── sessions.ts # Session management (GET, POST, etc.) │ │ │ ├── search.ts # Full-text search endpoints │ │ │ ├── projects.ts # Project management │ │ │ ├── sync.ts # Cloud sync endpoints │ │ │ └── blobs.ts # Blob storage endpoints │ │ └── validators/ # Zod request validation schemas │ │ ├── sessions.ts │ │ ├── search.ts │ │ ├── projects.ts │ │ ├── sync.ts │ │ └── index.ts │ │ │ ├── db/ # Database layer │ │ ├── index.ts # Main DB module exports │ │ ├── connections/ # Database connections │ │ │ ├── specstory.ts # SpecStory main database │ │ │ ├── claude.ts # Claude Code store.db (read-only) │ │ │ └── swarm.ts # Swarm memory.db (read-only) │ │ ├── schema/ # Drizzle ORM schemas │ │ │ ├── specstory.ts # Projects, history files, backups, sync │ │ │ ├── sessions.ts # Session and message data │ │ │ ├── claude-store.ts # Claude Code blob storage schema │ │ │ └── swarm-memory.ts # Swarm memory schema │ │ ├── repositories/ # Data access layer │ │ │ ├── sessions-repository.ts │ │ │ ├── projects-repository.ts │ │ │ ├── sync-repository.ts │ │ │ └── index.ts │ │ └── queries/ # Specialized queries │ │ ├── session-search.ts │ │ ├── project-stats.ts │ │ └── index.ts │ │ │ ├── cli/ # Command-line interface │ │ ├── index.ts # CLI main entry with Commander │ │ ├── commands/ │ │ │ ├── import.ts # Import JSONL session data │ │ │ ├── export.ts # Export to Markdown/JSON │ │ │ ├── search.ts # Search CLI │ │ │ ├── sync.ts # Manage cloud sync │ │ │ └── migrate.ts # Run migrations │ │ └── utils/ │ │ ├── output.ts # Output formatting │ │ └── progress.ts # Progress tracking │ │ │ └── lib/ # Shared utilities │ ├── config.ts # App configuration from env vars │ ├── logger.ts # Logging utility │ ├── errors.ts # Custom error classes │ ├── index.ts │ ├── markdown/ │ │ └── session-exporter.ts # Convert sessions to Markdown │ └── sync/ # Cloud sync utilities │ ├── drizzle/ # Database migrations │ └── migrations/ │ └── specstory/ │ ├── 0000_complete_vertigo.sql # Initial schema migration │ └── meta/ # Migration metadata │ ├── .specstory/ # Local SpecStory metadata │ ├── specstory.db # Main SQLite database (86KB) │ ├── specstory.db-shm # WAL temp file │ ├── specstory.db-wal # Write-ahead log │ ├── .project.json # Project metadata │ └── history/ # (Markdown session files) │ ├── specstory/ # Submodule - actual SpecStory CLI repo │ └── .git/ # Git repository │ ├── node_modules/ # Dependencies (92 top-level packages) ├── .gitignore └── README files ``` ### 4. Database Schema Overview The system manages 4 separate SQLite databases: **Primary: SpecStory Database (specstory.db)** - `projects` - Project metadata and workspace tracking - `history_files` - Markdown session file metadata - `ai_rules_backups` - GOOD feature (Git-related AI rule backups) - `cloud_sync_state` - Cloud synchronization status **Secondary: Sessions Database** (tracked separately) - `sessions` - Individual chat session records - `session_messages` - Messages within sessions with blob references - `blob_cache` - Cached blob content from Claude Code **Read-only Integrations**: - `claude-store.ts` - Schema for Claude Code's store.db (blobs, metadata) - `swarm-memory.ts` - Schema for Swarm memory database ### 5. Configuration **Environment Variables** (app/lib/config.ts): ``` PORT=7382 (default) HOST=0.0.0.0 NODE_ENV=development|production|test DB_PATH=.specstory/specstory.db ENABLE_WAL=true LOG_LEVEL=debug|info|warn|error PRETTY_LOGS=true CORS_ENABLED=true CORS_ORIGINS=* (comma-separated) API_PREFIX=/api ENABLE_CLOUD_SYNC=false (opt-in) ENABLE_BACKUPS=true ``` **Project Metadata** (.specstory/.project.json): ```json { "workspace_id": "unique-id", "workspace_id_at": "ISO timestamp", "project_name": "project-name", "cloud_sync": true|false, "user_id": "email@example.com" } ``` ### 6. API Architecture **Framework**: Hono v4 (lightweight, TypeScript-native) **Middleware Stack**: 1. CORS (conditional) 2. Pretty JSON formatter (development) 3. Request logger 4. Database context injection **API Routes** (mounted at /api prefix): - `/api/sessions` - Session CRUD operations with pagination - `/api/search` - Full-text search across sessions - `/api/projects` - Project management - `/api/sync` - Cloud synchronization control - `/api/blobs` - Blob storage access - `/health` - Health check endpoint **Key Features**: - Error handling middleware - Request validation with Zod - Database context injection via middleware - RESTful design ### 7. CLI Architecture **Framework**: Commander.js v14 **Available Commands**: - `import` - Import JSONL session data (global/project/all options) - `export` - Export sessions to Markdown or JSON format - `search` - Search sessions with query and filters - `sync` - Manage cloud sync (status, start, stop) - `migrate` - Run database migrations - `stats` - Show database statistics ### 8. Build System **Package.json Scripts**: ```json { "dev": "bun --watch app/api/server.ts", // Watch mode "start": "bun app/api/server.ts", // Run API server "build": "tsc", // TypeScript compilation "studio": "drizzle-kit studio", // Database UI "generate": "drizzle-kit generate", // Generate migrations "migrate": "tsx src/migrate.ts", // Run migrations "type-check": "tsc --noEmit" // Type checking only } ``` **TypeScript Configuration** (tsconfig.json): - Target: ES2022 - Module: ESNext - Strict mode enabled - Module resolution: bundler - Path aliases: `@/db/*`, `@/api/*`, `@/cli/*`, `@/lib/*` - Output: ./dist (compiled JavaScript) ### 9. Testing & Quality Assurance **Current State**: No test infrastructure found - No test files (*.test.ts, *.spec.ts) - No Jest/Vitest configuration - No unit test setup - **This is a gap that should be addressed** ### 10. Key Metrics - **Total TypeScript Files**: 43 files - **Total Lines of Code**: ~4,849 lines - **Package Version**: v0.1.0 - **License**: ISC - **Node Version**: >=14 (implied by better-sqlite3 native bindings) ### 11. Key Features & Patterns **Data Access Patterns**: - Repository pattern (sessions, projects, sync) - Query layer for specialized operations (search, stats) - Connection factories for multi-database support **Error Handling**: - Custom error classes (NotFoundError, BadRequestError, etc.) - Global error handler middleware - Typed error responses **Configuration**: - Environment-based configuration - Feature flags for optional features (cloud sync, backups) - Log level control **Database Features**: - WAL (Write-Ahead Logging) enabled for performance - Drizzle migrations for schema management - Type-safe schemas with inference ### 12. Integration Points 1. **Claude Code** - Reads from ~/.claude/projects/ and store.db 2. **Cloud Platform** - Optional sync to cloud.specstory.com 3. **Git Integration** - GOOD feature tracks AI rule backups with git commits 4. **File System** - Monitors and imports JSONL session files ### 13. Directory for Improvement - Testing infrastructure (Jest/Vitest) - Integration tests for API - Documentation for API endpoints - Error handling enhancements - Performance optimizations for large datasets This is a well-structured TypeScript/Node.js backend service using modern tooling (Bun, Hono, Drizzle ORM) with a clean layered architecture supporting multiple data sources and REST API operations.