syntaxis/docs/installation/installation-architecture.md

# Installation Architecture: Targets with Configs & Wrappers

**Status:** Analysis & Design Document
**Created:** November 15, 2025
**Purpose:** Document installation strategy for syntaxis binaries with configuration management

---

## 1. Current Installation System

### 1.1 Installation Scripts Infrastructure

**File:** `scripts/install-cli.nu` (NuShell)

**Current Capabilities:**
- Discovers binary crates in syntaxis (cli, api, tui, dashboard)
- Installs binaries to system PATH via `cargo install`
- Cleans up target/ directories (optional)
- Shows installation status
- Manages individual binary installation

**Current Limitations:**
```
✅ Installs binaries to ~/.cargo/bin/ (system PATH)
❌ Does NOT deploy configuration files
❌ Does NOT create wrapper scripts
❌ Does NOT manage config discovery at runtime
❌ No post-install configuration step
```

### 1.2 Manifest Management Infrastructure

**File:** `scripts/manifest.nu` (NuShell)

**Tracks:**
- Installed binaries (name, version, path, enabled/disabled status)
- Configurations (name, type, path, enabled/disabled)
- Installation metadata (creation date, root directory)

**Example Structure:**
```toml
# .syntaxis/manifest.toml (generated structure)
[syntaxis]
version = "0.1.0"
created_at = "2025-11-15"
installation_root = "/path/to/installation"

[binaries]
workspace = { enabled = true, installed_at = "2025-11-15", version = "0.1.0", path = "..." }
syntaxis-tui = { enabled = true, installed_at = "2025-11-15", version = "0.1.0", path = "..." }

[configurations]
# Currently empty - needs enhancement
```

### 1.3 Configuration Discovery System

**File:** `scripts/common/find-config.nu`

**Search Order:**
1. `.syntaxis/{filename}` - syntaxis specific
2. `.project/{filename}` - Generic project
3. `.coder/{filename}` - Documentation tracking
4. `{filename}` - Current directory fallback

**Current Usage:**
- Scripts use this to find config files at build/runtime
- Database discovery (find-db-path)
- TOML file discovery

---

## 2. Configuration System Analysis

### 2.1 Configuration File Locations

**Current Structure:**
```
syntaxis/
├── syntaxis/
│   ├── syntaxis-api-config.template.toml    ⚠️ NEEDS RENAME
│   └── configs/features/
│       ├── auth.toml.template
│       ├── cache.toml.template
│       ├── database.toml.template
│       ├── health.toml.template
│       ├── metrics.toml.template
│       ├── multi_tenant.toml.template
│       └── rate_limit.toml.template
│
├── shared/rust-api/shared-api-lib/
│   └── src/config/mod.rs                    (Config definitions)
│
└── .syntaxis/                    (Runtime configs after installation)
    ├── manifest.toml                        (Installation tracking)
    └── [configs deployed here at runtime]
```

### 2.2 Configuration Loading Flow

**Current (Hardcoded):**
```rust
// shared-api-lib/src/config/mod.rs
impl Config {
    pub fn load() -> Result<Self> {
        // 1. Try reading from env var
        let config_path = std::env::var("CONFIG_PATH")
            .unwrap_or_else(|_| "configs/default.toml".to_string());

        // 2. Load from file
        let content = std::fs::read_to_string(&config_path)?;

        // 3. Deserialize
        let config: Config = toml::from_str(&content)?;
        Ok(config)
    }
}
```

**Needs Enhancement:**
- Use find-config logic for standardized discovery
- Support multiple config locations
- Environment variable overrides
- Config validation and merging

### 2.3 Configuration Types

**Main Configuration:** `syntaxis-api-config.toml`
- Server settings (host, port)
- Database connection
- Logging level
- Feature flags

**Feature Configurations:** `configs/features/*.toml`
- auth.toml - Authentication settings
- database.toml - Database pooling
- metrics.toml - Prometheus settings
- rate_limit.toml - Rate limiting rules
- cache.toml - Caching configuration
- health.toml - Health check settings
- multi_tenant.toml - Multi-tenancy settings

**Missing Workspace-Specific Configs:**
- projects.toml - Project management settings
- tasks.toml - Task tracking configuration
- phases.toml - Phase lifecycle configuration
- audit.toml - Audit trail settings

---

## 3. Installation Targets Architecture

### 3.1 What is a "Target"?

In syntaxis context, a **target** is:

```
A compiled binary + its associated configs + runtime metadata

workspace (target)
├── Binary
│   └── ~/.cargo/bin/workspace  (executable)
├── Configuration
│   ├── ~/.config/core/workspace.toml          (main config)
│   └── ~/.config/core/features/*.toml         (feature configs)
├── Data
│   └── ~/.local/share/core/                   (runtime data)
├── Wrapper
│   └── /usr/local/bin/workspace                             (wrapper script)
└── Metadata
    └── .syntaxis/manifest.toml                   (installed version/path)
```

### 3.2 Target Types

**1. CLI Binary (syntaxis-cli)**
```
Purpose: Command-line interface
Executable: ~/.cargo/bin/workspace
Config: ~/.config/core/cli.toml
Data: ~/.local/share/core/cli/
Wrapper: Yes (setup env, find config, pass args)
```

**2. TUI Binary (syntaxis-tui)**
```
Purpose: Terminal UI interface
Executable: ~/.cargo/bin/syntaxis-tui
Config: ~/.config/core/tui.toml
Data: ~/.local/share/core/tui/
Wrapper: Yes (setup terminal, handle signals)
```

**3. API Server (syntaxis-api)**
```
Purpose: REST API server
Executable: ~/.cargo/bin/syntaxis-api
Config: ~/.config/core/api.toml
Data: ~/.local/share/core/api/
Wrapper: Yes (setup environment, manage process)
```

**4. Dashboard (syntaxis-dashboard)**
```
Purpose: Web UI
Type: Library + WASM frontend
Config: ~/.config/core/dashboard.toml
Data: ~/.local/share/core/dashboard/
Wrapper: Yes (manage server lifecycle)
```

---

## 4. Configuration Deployment Strategy

### 4.1 Configuration File Organization

**On Host System (After Installation):**
```
~/.config/core/
├── manifest.toml                    # Installation tracking
├── defaults.toml                    # Global defaults
├── workspace.toml                   # CLI config
├── syntaxis-tui.toml              # TUI config
├── syntaxis-api.toml              # API config
├── syntaxis-dashboard.toml        # Dashboard config
└── features/                        # Feature configs
    ├── auth.toml
    ├── cache.toml
    ├── database.toml
    ├── health.toml
    ├── metrics.toml
    ├── multi_tenant.toml
    └── rate_limit.toml

~/.local/share/core/
├── cli/                             # CLI runtime data
│   └── history.json
├── tui/                             # TUI runtime data
│   └── state.json
├── api/                             # API runtime data
│   ├── workspace.db
│   └── logs/
└── dashboard/                       # Dashboard runtime data
    └── cache/
```

### 4.2 Configuration Template Deployment

**During Installation:**
1. Copy `syntaxis-api-config.template.toml` → `~/.config/core/syntaxis-api.toml`
2. Copy `configs/features/*.toml.template` → `~/.config/core/features/*.toml`
3. Create `.syntaxis/manifest.toml` with installation metadata
4. Register installed configurations in manifest

**Version Management:**
```toml
# manifest.toml entry
[configurations.syntaxis-api]
enabled = true
type = "main"
path = "~/.config/core/syntaxis-api.toml"
version = "0.1.0"
deployed_from = "syntaxis/syntaxis-api-config.template.toml"
deployed_at = "2025-11-15T10:30:00Z"
```

---

## 5. Wrapper Scripts Architecture

### 5.1 Purpose of Wrappers

Wrapper scripts sit between the user/system and the binary, providing:

```
User Command: workspace --version
         ↓
Wrapper Script: workspace (wrapper)
         ↓ (setup environment)
         ├─ Find config file
         ├─ Set environment variables
         ├─ Validate config
         ├─ Setup logging
         └─ Call actual binary
         ↓
Actual Binary: ~/.cargo/bin/workspace.real
         ↓
Output to User
```

### 5.2 Wrapper Implementation Strategy

**Type 1: Shell-based Wrappers** (NuShell or Bash)

```nu
#!/usr/bin/env nu

# workspace wrapper - Setup environment and call actual binary

# 1. Find configuration
use scripts/common/find-config.nu [find-config]
let config_file = (find-config "workspace.toml")

# 2. Setup environment
let config_dir = (
    if ($config_file | is-empty) {
        "~/.config/syntaxis"
    } else {
        ($config_file | path dirname)
    }
)

# 3. Set environment variables
$env.WORKSPACE_CONFIG_DIR = ($config_dir | path expand)
$env.WORKSPACE_DATA_DIR = ("~/.local/share/syntaxis" | path expand)
$env.WORKSPACE_HOME = (pwd)

# 4. Call actual binary with arguments
~/.cargo/bin/workspace.real ...$args
```

**Type 2: Rust-based Wrappers**

```rust
// workspace-wrapper/main.rs
use std::env;
use std::process::Command;

fn main() {
    // 1. Find and load config
    let config_dir = find_config_dir()
        .unwrap_or_else(|| get_default_config_dir());

    // 2. Setup environment
    env::set_var("WORKSPACE_CONFIG_DIR", &config_dir);
    env::set_var("WORKSPACE_DATA_DIR", get_data_dir());

    // 3. Validate config
    validate_config(&config_dir)
        .expect("Configuration validation failed");

    // 4. Call actual binary
    let mut cmd = Command::new(
        get_actual_binary_path()
    );

    cmd.args(env::args().skip(1));

    let status = cmd.status()
        .expect("Failed to execute binary");

    std::process::exit(status.code().unwrap_or(1));
}
```

### 5.3 Wrapper Functions

**1. Configuration Discovery & Validation**
```
Find config file
↓
Validate TOML syntax
↓
Check required fields
↓
Merge with feature configs
↓
Set CONFIG_PATH env var
```

**2. Environment Setup**
```
Set WORKSPACE_HOME
Set WORKSPACE_CONFIG_DIR
Set WORKSPACE_DATA_DIR
Set WORKSPACE_LOG_LEVEL (from config)
Set RUST_LOG (from log_level config)
```

**3. Pre-execution Hooks**
```
Check database connectivity (for API)
Create data directories if missing
Setup logging appenders
Validate feature configurations
```

**4. Post-execution Cleanup**
```
Flush logs
Close database connections
Cleanup temp files
```

---

## 6. Installation Flow

### 6.1 Complete Installation Process

```
┌─────────────────────────────────────────────────────────┐
│ User: just scripts-install or install-cli.nu all        │
└─────────────┬───────────────────────────────────────────┘
              │
              ├─ 1. DISCOVERY
              │   └─ Find all binary crates in workspace
              │
              ├─ 2. COMPILATION
              │   └─ cargo build --release
              │
              ├─ 3. BINARY INSTALLATION
              │   └─ cargo install --path {crate}
              │       └─ Binary placed in ~/.cargo/bin/
              │
              ├─ 4. CONFIGURATION DEPLOYMENT
              │   ├─ Create ~/.config/core/
              │   ├─ Copy syntaxis-api-config.template.toml
              │   ├─ Copy features/*.toml.template
              │   └─ Parse and validate all configs
              │
              ├─ 5. WRAPPER INSTALLATION
              │   ├─ Rename ~/.cargo/bin/workspace → ~/.cargo/bin/workspace.real
              │   ├─ Create wrapper script at ~/.cargo/bin/workspace
              │   └─ Make wrapper executable
              │
              ├─ 6. MANIFEST REGISTRATION
              │   ├─ Load or create .syntaxis/manifest.toml
              │   ├─ Register binary (name, version, path)
              │   ├─ Register configurations
              │   └─ Save manifest
              │
              └─ 7. VERIFICATION
                  ├─ workspace --version (test wrapper)
                  ├─ Test config discovery
                  ├─ Validate environment setup
                  └─ Print installation summary
```

### 6.2 Installation Script Pseudocode

```nu
#!/usr/bin/env nu

# Phase 1: Compile binaries
cargo build --release

# Phase 2: Install binaries to ~/.cargo/bin/
for binary in [workspace syntaxis-tui syntaxis-api] {
    cargo install --path core/crates/{binary}
}

# Phase 3: Deploy configurations
let config_dir = "~/.config/syntaxis"
mkdir -p $config_dir
mkdir -p $"($config_dir)/features"

# Copy main configs
cp syntaxis/syntaxis-api-config.template.toml \
   "$config_dir/syntaxis-api.toml"

# Copy feature configs
cp syntaxis/configs/features/*.toml.template \
   "$config_dir/features/"

# Phase 4: Install wrappers
for binary in [workspace syntaxis-tui syntaxis-api] {
    let binary_path = $"~/.cargo/bin/($binary)"

    # Rename actual binary
    mv $binary_path $"$binary_path.real"

    # Create wrapper script
    create-wrapper-script $binary $binary_path

    # Make executable
    chmod +x $binary_path
}

# Phase 5: Register in manifest
register-binary "workspace" "0.1.0" "~/.cargo/bin/workspace"
register-config "syntaxis-api" "main" "~/.config/core/syntaxis-api.toml"

# Phase 6: Verify installation
print "✅ Installation complete"
print ""
print "Test with:"
print "  workspace --version"
print "  syntaxis-tui"
```

---

## 7. Proposed Implementation Roadmap

### Phase 1: Configuration Deployment (Weeks 1-2)

**Tasks:**
1. Rename `syntaxis-api-config.template.toml` → `syntaxis-api-config.template.toml`
2. Create workspace-specific feature templates:
   - `configs/features/projects.toml.template`
   - `configs/features/tasks.toml.template`
   - `configs/features/phases.toml.template`
   - `configs/features/audit.toml.template`
3. Update `install-cli.nu` to copy config templates
4. Create `~/.config/core/` during installation

**Deliverables:**
- ✅ Config templates renamed and created
- ✅ Installation script copies configs
- ✅ Configuration files deployed to standard location

### Phase 2: Wrapper Script Implementation (Weeks 3-4)

**Tasks:**
1. Create wrapper script generator
2. Implement configuration discovery in wrappers
3. Setup environment variables
4. Integrate manifest management
5. Test wrapper functionality

**Deliverables:**
- ✅ Wrapper scripts for workspace, syntaxis-tui, syntaxis-api
- ✅ Config discovery working
- ✅ Environment properly setup

### Phase 3: Manifest Enhancement (Weeks 4-5)

**Tasks:**
1. Extend manifest.toml schema to track configs
2. Update manifest.nu to register configurations
3. Add config validation to manifest
4. Create config version tracking

**Deliverables:**
- ✅ Manifest tracks installed configs
- ✅ Config versions tracked
- ✅ Easy rollback capability

### Phase 4: Documentation & Testing (Weeks 5-6)

**Tasks:**
1. Create installation guide
2. Create configuration guide
3. Write wrapper script documentation
4. Create troubleshooting guide
5. Add integration tests

**Deliverables:**
- ✅ docs/installation-guide.md
- ✅ docs/configuration.md
- ✅ WRAPPER_GUIDE.md
- ✅ Integration tests passing

---

## 8. Key Design Decisions

### 8.1 Configuration Location

**Decision:** `~/.config/core/`

**Rationale:**
- Follows XDG Base Directory Specification
- Separates configs from binaries
- Easy to backup/restore
- Works on macOS, Linux, Windows (with WSL)
- Per-user isolation

**Alternative:** `/etc/core/` (would require sudo)

### 8.2 Wrapper Language

**Decision:** NuShell for maximum compatibility

**Rationale:**
- Consistent with existing workspace scripts
- Cross-platform (Windows, macOS, Linux)
- Rich scripting capabilities
- Same repo standard tool

**Alternative:** Rust (compile-time, higher performance)

### 8.3 Configuration Format

**Decision:** TOML (continue existing approach)

**Rationale:**
- Already in use throughout workspace
- Human-readable
- Serde support for validation
- Feature-specific configs easy to compose

### 8.4 Manifest Location

**Decision:** `.syntaxis/manifest.toml`

**Rationale:**
- Version-controlled for tracking
- Centralized installation metadata
- Easy to query installation state
- Clear audit trail

---

## 9. Security Considerations

### 9.1 Configuration File Permissions

```bash
# Config files should be readable by user only
chmod 600 ~/.config/core/*.toml

# Data directories should be user-writable
chmod 700 ~/.local/share/core/
```

### 9.2 Wrapper Script Security

```bash
# Wrapper scripts should not be world-writable
chmod 755 ~/.cargo/bin/workspace

# Binaries should not be world-writable
chmod 755 ~/.cargo/bin/workspace.real
```

### 9.3 Environment Variable Injection

**Risk:** Wrapper script loads untrusted configs

**Mitigation:**
1. Validate TOML syntax before loading
2. Check file ownership (must be current user)
3. Validate required fields before use
4. Reject unknown configuration keys (strict mode)

### 9.4 Database Access

**Risk:** Database path from config could point to sensitive files

**Mitigation:**
1. Validate database path is within `~/.local/share/core/`
2. Check database file permissions
3. Require explicit user approval for non-standard paths

---

## 10. Examples

### 10.1 User Installation Workflow

```bash
# 1. Install all targets
$ just scripts-install
  🔨 Installing syntaxis binaries...
  ✅ workspace: Installed successfully
  ✅ syntaxis-tui: Installed successfully
  ✅ syntaxis-api: Installed successfully

  📋 Configurations deployed to:
    ~/.config/core/
    └── syntaxis-api.toml
    └── features/
        ├── auth.toml
        ├── database.toml
        ├── ...

# 2. Check installation
$ just scripts-status
  📊 Installation Status
  ✅ workspace (CLI) - Installed
  ✅ syntaxis-tui (TUI) - Installed
  ✅ syntaxis-api (API) - Installed (WIP)

# 3. Verify wrapper works
$ workspace --version
  syntaxis v0.1.0

  Config loaded from: ~/.config/core/syntaxis-api.toml
  Data directory: ~/.local/share/core/

# 4. Edit configuration
$ nano ~/.config/core/syntaxis-api.toml

# 5. Restart to apply changes
$ syntaxis-api
  ✅ Config validated
  ✅ Features loaded: auth, database, metrics
  ✅ Server listening on 0.0.0.0:8080
```

### 10.2 Configuration Discovery at Runtime

```rust
// Inside binary (syntaxis-api or similar)

use std::env;
use std::path::PathBuf;

fn load_config() -> Result<Config> {
    // 1. Check explicit environment variable
    if let Ok(path) = env::var("WORKSPACE_CONFIG_PATH") {
        return load_from_path(&path);
    }

    // 2. Use WORKSPACE_CONFIG_DIR (set by wrapper)
    let config_dir = env::var("WORKSPACE_CONFIG_DIR")
        .unwrap_or_else(|_| get_default_config_dir());

    // 3. Try standard locations
    let candidates = vec![
        PathBuf::from(&config_dir).join("syntaxis-api.toml"),
        PathBuf::from(&config_dir).join("default.toml"),
        PathBuf::from(env::current_dir()?).join("syntaxis-api.toml"),
    ];

    for path in candidates {
        if path.exists() {
            return load_from_path(&path);
        }
    }

    Err("No configuration found".into())
}
```

---

## 11. Files to Create/Modify

### Create New Files
- [ ] `scripts/install-targets.nu` - Enhanced installation with configs & wrappers
- [ ] `scripts/deploy-configs.nu` - Configuration deployment script
- [ ] `scripts/create-wrappers.nu` - Wrapper script generator
- [ ] `syntaxis/configs/features/projects.toml.template`
- [ ] `syntaxis/configs/features/tasks.toml.template`
- [ ] `syntaxis/configs/features/phases.toml.template`
- [ ] `syntaxis/configs/features/audit.toml.template`
- [ ] `docs/installation-guide.md` - User-facing installation documentation
- [ ] `docs/configuration.md` - Configuration management guide
- [ ] `WRAPPER_DESIGN.md` - Technical wrapper documentation

### Modify Existing Files
- [ ] `scripts/install-cli.nu` - Add config deployment
- [ ] `scripts/manifest.nu` - Add config registration
- [ ] `syntaxis/syntaxis-api-config.template.toml` → `syntaxis-api-config.template.toml`
- [ ] `Justfile` - Add installation targets recipe
- [ ] `shared/rust-api/shared-api-lib/src/config/mod.rs` - Integrate find-config

### Update Documentation
- [ ] README.md - Add installation instructions
- [ ] syntaxis/README.md - Add wrapper documentation
- [ ] .claude/ guidelines - Add installation best practices

---

## 12. Summary

### Current State
- ✅ Basic binary installation working
- ✅ Manifest tracking available
- ✅ Config discovery system exists
- ❌ Configs not deployed with binaries
- ❌ No wrapper scripts
- ❌ No environment setup at runtime

### Target State (After Implementation)
- ✅ Complete binary installation with configs
- ✅ Wrapper scripts setup environment
- ✅ Configuration validation
- ✅ Environment variable management
- ✅ Standardized installation locations
- ✅ Easy configuration management
- ✅ Installation verification

### Next Steps
1. Review this document with team
2. Confirm design decisions
3. Begin Phase 1 (configuration deployment)
4. Follow phased roadmap
5. Write integration tests as work progresses

---

**Document Version:** 1.0
**Status:** Design Review Ready
**Last Updated:** November 15, 2025