From 7ca65bfd596aab5fcee627bc968ff512d51ce36c Mon Sep 17 00:00:00 2001
From: Thomas Hallock <thomas@evolutioniq.com>
Date: Sun, 14 Sep 2025 08:03:53 -0500
Subject: [PATCH] feat: add development tooling and comprehensive setup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Create development setup script for one-command installation
- Add parallel development server startup script
- Include comprehensive development documentation
- Set up type checking, building, and dependency management
- Provide troubleshooting guide and architecture overview

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 DEVELOPMENT.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++
 scripts/dev.sh | 34 ++++++++++++++++++++
 setup-dev.sh   | 77 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 198 insertions(+)
 create mode 100644 DEVELOPMENT.md
 create mode 100755 scripts/dev.sh
 create mode 100755 setup-dev.sh

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 00000000..fd590714
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,87 @@
+# Development Setup
+
+This document describes how to set up and run the Soroban Flashcard Generator for development.
+
+## Architecture
+
+This is a monorepo with the following structure:
+
+```
+.
+├── apps/
+│   └── web/                 # Next.js web application
+├── packages/
+│   └── core/
+│       └── client/
+│           ├── node/        # @soroban/core - Node.js TypeScript bindings
+│           └── typescript/  # @soroban/client - TypeScript utilities
+└── scripts/                 # Development scripts
+```
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm 8+
+- Python 3.8+
+- Typst (for PDF generation)
+- qpdf (optional, for PDF optimization)
+
+## Quick Start
+
+1. **Initial Setup**
+   ```bash
+   pnpm setup
+   ```
+   This script will:
+   - Install all dependencies
+   - Build the core packages
+   - Set up Panda CSS
+   - Run type checks
+
+2. **Development**
+   ```bash
+   pnpm dev
+   ```
+   This starts all development servers in parallel using Turborepo.
+
+   The web app will be available at: http://localhost:3000
+
+## Available Scripts
+
+- `pnpm setup` - Full development environment setup
+- `pnpm dev` - Start all development servers
+- `pnpm build` - Build all packages
+- `pnpm type-check` - Run TypeScript checks
+- `pnpm lint` - Run linting
+- `pnpm test` - Run tests
+- `pnpm clean` - Clean build artifacts
+
+## Packages
+
+### @soroban/core
+Node.js TypeScript bindings that call the Python generator directly via `child_process`. Located in `packages/core/client/node/`.
+
+### @soroban/web
+Next.js web application with beautiful UI built using:
+- **Panda CSS** for styling
+- **TanStack Form** for form management
+- **Radix UI** primitives for accessibility
+- **Lucide React** for icons
+
+## Development Notes
+
+1. **TypeScript Bindings**: The web app calls Python directly through TypeScript bindings, not via a FastAPI server.
+
+2. **Styling**: Uses Panda CSS instead of Tailwind. Run `pnpm panda` in the web app to regenerate styles.
+
+3. **Monorepo**: Built packages must be available before the web app can use them. The setup script handles this automatically.
+
+4. **Asset Storage**: Generated files are temporarily stored in memory. In production, use Redis or a database.
+
+## Troubleshooting
+
+**TypeScript errors**: Run `pnpm type-check` to see detailed errors.
+
+**Build issues**: Try `pnpm clean` then `pnpm setup` to rebuild everything.
+
+**Python errors**: Ensure Python 3, Typst, and qpdf are installed and accessible in PATH.
\ No newline at end of file
diff --git a/scripts/dev.sh b/scripts/dev.sh
new file mode 100755
index 00000000..bb25a0e9
--- /dev/null
+++ b/scripts/dev.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# Development startup script for Soroban Flashcard Generator
+# This script starts all development services concurrently
+
+set -e
+
+echo "🚀 Starting Soroban Flashcard Generator Development Environment"
+echo ""
+
+# Check if we're in the right directory
+if [ ! -f "package.json" ]; then
+    echo "❌ Please run this script from the project root directory"
+    exit 1
+fi
+
+# Build packages if needed
+echo "🔨 Building packages..."
+pnpm turbo run build --filter="@soroban/*" --continue
+
+# Generate Panda CSS
+echo "🎨 Generating Panda CSS..."
+cd apps/web && pnpm panda && cd ../..
+
+# Start development servers
+echo "🌟 Starting development servers..."
+echo ""
+echo "📝 Available endpoints:"
+echo "   • Web App: http://localhost:3000"
+echo "   • API Health: http://localhost:3000/api/generate"
+echo ""
+
+# Use Turborepo to run development in parallel
+pnpm turbo run dev --parallel
\ No newline at end of file
diff --git a/setup-dev.sh b/setup-dev.sh
new file mode 100755
index 00000000..63936192
--- /dev/null
+++ b/setup-dev.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+
+echo "🚀 Setting up Soroban Flashcard Generator Development Environment"
+echo ""
+
+# Check for required tools
+echo "📋 Checking requirements..."
+
+if ! command -v pnpm &> /dev/null; then
+    echo "❌ pnpm is required but not installed. Please install pnpm first."
+    echo "   npm install -g pnpm"
+    exit 1
+fi
+
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 is required but not installed."
+    exit 1
+fi
+
+echo "✅ All requirements satisfied"
+echo ""
+
+# Install dependencies
+echo "📦 Installing dependencies..."
+pnpm install --frozen-lockfile=false
+
+if [ $? -ne 0 ]; then
+    echo "❌ Failed to install dependencies"
+    exit 1
+fi
+
+echo "✅ Dependencies installed"
+echo ""
+
+# Build core packages
+echo "🔨 Building core packages..."
+
+# Build TypeScript client
+echo "  Building @soroban/client..."
+cd packages/core/client/typescript
+pnpm build
+cd ../../../../
+
+# Build Node client
+echo "  Building @soroban/core..."
+cd packages/core/client/node
+pnpm build
+cd ../../../../
+
+echo "✅ Core packages built"
+echo ""
+
+# Build web app dependencies
+echo "🎨 Setting up Panda CSS..."
+cd apps/web
+pnpm build:css --config
+cd ../../
+
+echo "✅ Panda CSS configured"
+echo ""
+
+# Final verification
+echo "🧪 Running type checks..."
+pnpm turbo run type-check
+
+if [ $? -eq 0 ]; then
+    echo ""
+    echo "🎉 Development environment setup complete!"
+    echo ""
+    echo "📋 Next steps:"
+    echo "   • Run 'pnpm dev' to start development server"
+    echo "   • Run 'pnpm build' to build all packages"
+    echo "   • Run 'pnpm turbo run dev' to start all services"
+    echo ""
+else
+    echo "⚠️  Setup complete but type checks failed. Review the output above."
+fi
\ No newline at end of file