Files

Joakim ae9ae7e442 docs: update all documentation for unified binary architecture

📚 **Complete Documentation Overhaul**

**Updated Files:**
✅ **README.md** - Updated commands, configuration, and workflow
✅ **COMMANDS.md** - New comprehensive command reference
✅ **INTEGRATION-SUMMARY.md** - Updated architecture overview
✅ **insertr-server/README.md** - Redirect to unified binary docs

**Key Documentation Changes:**

🔧 **Unified Binary Commands:**
- Updated all examples to use `./insertr enhance` and `./insertr serve`
- Removed references to separate CLI/server binaries
- Added comprehensive configuration documentation

⚙️ **Configuration Section:**
- Added YAML configuration examples (`insertr.yaml`)
- Documented environment variables (`INSERTR_*`)
- Explained configuration precedence (CLI → env → YAML → defaults)

📖 **Command Reference (COMMANDS.md):**
- Complete reference for all commands and flags
- Usage patterns for development and production
- API endpoint documentation
- Error handling and debugging guides
- CI/CD integration examples

🏗️ **Architecture Updates:**
- Updated development workflow instructions
- Fixed CLI → Binary terminology
- Updated hot reload and build process documentation

**Migration Notes:**
- All functionality preserved in unified binary
- Simplified development workflow with `just dev`
- Single executable for all operations

2025-09-10 18:12:31 +02:00

4.3 KiB

Raw Blame History

Unified Binary Architecture Complete ✅

🎯 What Was Accomplished

Successfully refactored insertr-cli and insertr-server into a unified insertr binary, creating a simpler, more maintainable architecture while preserving all functionality.

🚀 Unified Binary Experience

Single Binary Commands

./insertr enhance   # 🔨 Build-time content injection
./insertr serve     # 🔌 Runtime API server
./insertr --help    # 📖 Complete command reference

Simplified Development

just dev         # 🔥 Full-stack development (PRIMARY)
just serve       # API server only (development)  
just enhance     # Build-time enhancement only

Enhanced Build Pipeline

just build       # Now builds: Library + Unified Binary (single executable)
npm run build    # Same - builds complete stack via scripts/build.js

Smart Configuration

YAML Configuration: insertr.yaml with smart defaults
Environment Variables: INSERTR_* prefix for all settings
CLI Flag Precedence: Command-line flags override config and env vars
Database Flexibility: SQLite for development, PostgreSQL for production

📋 Technical Architecture Changes

1. Unified Command Structure

Single Binary: insertr handles both enhance and serve operations
Cobra CLI: Professional command structure with subcommands
Viper Configuration: YAML + environment + CLI flag precedence
Shared Database Layer: Single source of truth for content models

2. Preserved Database Architecture

sqlc Code Generation: Maintained type-safe database operations
Multi-Database Support: SQLite (development) and PostgreSQL (production)
Version Control System: Complete edit history with rollback capabilities
Database Abstraction: Runtime database type detection

3. Enhanced Build Integration

scripts/build.js builds unified binary with embedded library assets
justfile updated for unified binary commands
Air configuration for hot reload during development
Single binary deployment for all use cases

4. Configuration Flexibility

YAML Config: insertr.yaml for declarative configuration
Environment Variables: INSERTR_* prefixed for all settings
CLI Precedence: Command flags override file and env config
Smart Defaults: Zero-configuration development workflow

🔄 Simplified Development Workflow

Primary Development (Default)

just dev         # or npm run dev
# Starts: insertr serve (8080) + Demo site (3000)  
# Complete CMS experience with unified binary

Build-Time Enhancement

just enhance     # Build-time content injection
./insertr enhance demo-site/ --output ./dist --mock
./insertr enhance src/ --api https://cms.example.com

Production Deployment

./insertr serve --db "postgresql://user:pass@host/db"
./insertr --config production.yaml serve

✅ Migration Benefits Achieved

All functionality preserved with architectural improvements:

✅ Single Binary: No more separate CLI and server binaries
✅ Shared Codebase: Database models, validation, and logic unified
✅ Flexible Configuration: YAML, environment, and CLI flag support
✅ Development Workflow: Hot reload with air for unified binary
✅ Production Ready: Same binary handles build-time and runtime
✅ Database Architecture: Preserved sophisticated sqlc multi-DB setup

🏗️ Architecture Diagram

Before: Separate Binaries

insertr-cli/     insertr-server/
     ↓                ↓
  enhance          serve
     ↓                ↓
  Build-time      Runtime

After: Unified Binary

       insertr
      ↙        ↘
   enhance    serve
      ↓         ↓
  Build-time Runtime
      ↓         ↓
   Same Database Layer
   Same Configuration
   Same Content Models

🎉 Result

The architecture is now unified and maintainable:

Single Source of Truth - No duplicate database or content logic
Simplified Deployment - One binary for all use cases
Better Developer Experience - Consistent configuration and commands
Production Flexibility - Build-time enhancement OR runtime API OR both

Insertr unified binary is production-ready with improved maintainability! 🚀

4.3 KiB Raw Blame History