Joakim
ae9ae7e442
📚 **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
125 lines
4.3 KiB
Markdown
125 lines
4.3 KiB
Markdown
# 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**
|
|
```bash
|
|
./insertr enhance # 🔨 Build-time content injection
|
|
./insertr serve # 🔌 Runtime API server
|
|
./insertr --help # 📖 Complete command reference
|
|
```
|
|
|
|
### **Simplified Development**
|
|
```bash
|
|
just dev # 🔥 Full-stack development (PRIMARY)
|
|
just serve # API server only (development)
|
|
just enhance # Build-time enhancement only
|
|
```
|
|
|
|
### **Enhanced Build Pipeline**
|
|
```bash
|
|
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)**
|
|
```bash
|
|
just dev # or npm run dev
|
|
# Starts: insertr serve (8080) + Demo site (3000)
|
|
# Complete CMS experience with unified binary
|
|
```
|
|
|
|
### **Build-Time Enhancement**
|
|
```bash
|
|
just enhance # Build-time content injection
|
|
./insertr enhance demo-site/ --output ./dist --mock
|
|
./insertr enhance src/ --api https://cms.example.com
|
|
```
|
|
|
|
### **Production Deployment**
|
|
```bash
|
|
./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!** 🚀 |