SquadLogic

Multi-agent desktop application for QA & DevOps automation. Built with Go + Wails v2 (Svelte/TypeScript frontend).

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Wails Desktop Shell                   │
├─────────────┬───────────────────────────────────────────┤
│  Sidebar    │              Main Content                  │
│             │  ┌─────────────────────────────────────┐  │
│  Dashboard  │  │  Dashboard / Flow Graph / Mind Map  │  │
│  Flow Graph │  │  Agents / Investigations            │  │
│  Mind Map   │  │  Chat / Discovery / Workflows       │  │
│  Agents     │  └─────────────────────────────────────┘  │
│  Chat       │                                            │
│  Discovery  │                                            │
│  ...        │                                            │
├─────────────┴───────────────────────────────────────────┤
│                    Go Backend (app.go)                    │
│                    ~120 exported bindings                 │
├──────────┬──────────┬───────────┬───────────┬───────────┤
│ EventBus │Supervisor│ Security  │  Skills   │  Agents   │
│ Chat/LLM │ JobQueue │ OIDC/Auth │ Registry  │(17 total) │
│ Store    │ Workflow │ Vault     │ Executor  │           │
│ Media    │ Daemon   │ Approval  │ Kill Ctrl │           │
└──────────┴──────────┴───────────┴───────────┴───────────┘

Tech Stack

Go Dependencies (Direct)

Frontend Dependencies

Agents

Security

• Authentication: Entra ID (Azure AD), Keycloak, and Generic OIDC providers
  • Auth Code + PKCE, Device Code, and Client Credentials flows
  • In-memory + disk token cache with automatic refresh
• Basic Auth & API Keys: Supported for API calls via AuthMiddleware
• Credential Store: AES-256-GCM encrypted at-rest vault (~/.squad_logic/vault/)
• TLS/mTLS: Certificate loading with automatic fsnotify-based rotation
• Corporate Proxy: Routes all HTTP traffic through configured proxy (HTTPS_PROXY)
  • go:debug x509negativeserial=1 for corporate MITM proxy certificate compatibility
• Audit Log: Append-only JSONL audit trail of all operations with optional risk-level classification
• Action Risk Classification: Three-tier model — read_only, mutating, destructive — applied to every agent job
• Human-in-the-Loop Approval Gates: Destructive jobs pause and require explicit human approval before execution
• Kill Switch: Instantly cancel running jobs or entire investigations via KillJob / KillInvestigation
• Read-Only DB: Optional read-only mode restriction per database connection

Frontend Views

Project Structure

.
├── main.go                          # Wails entry point, proxy env setup, GODEBUG x509
├── app.go                           # Main App struct (~110 bindings), Go→frontend API
├── go.mod / go.sum                  # Go module definition
├── wails.json                       # Wails build configuration
├── internal/
│   ├── config/config.go             # App configuration (all structs + defaults + Load/Save)
│   ├── core/
│   │   ├── types.go                 # Domain types (Agent, Job, Result, Investigation, Skill, etc.)
│   │   ├── eventbus.go              # Pub/sub event system, FlowGraph derivation
│   │   └── discovery.go             # Discovery types (DiscoveredPage, DiscoveredElement, DiscoveryAuth)
│   ├── security/
│   │   ├── proxy.go                 # Corporate proxy transport factory
│   │   ├── credential_store.go      # AES-256-GCM encrypted vault
│   │   ├── cert_manager.go          # TLS/mTLS cert loading + fsnotify rotation
│   │   ├── oidc_types.go            # Token, OIDCProvider interface
│   │   ├── oidc_entra.go            # Microsoft Entra ID provider
│   │   ├── oidc_keycloak.go         # Keycloak OIDC provider
│   │   ├── oidc_generic.go          # Generic OIDC with discovery
│   │   ├── token_cache.go           # In-memory + disk token cache with auto-refresh
│   │   └── auth_middleware.go       # Auth injection for HTTP requests
│   ├── engine/
│   │   ├── supervisor.go            # Agent orchestration, worker pool, approval gates, kill switch
│   │   ├── jobqueue.go              # Priority-based heap job queue
│   │   ├── state.go                 # Investigation/result/status tracking
│   │   └── daemon.go                # Background scheduler for recurring agent tasks
│   ├── agents/
│   │   ├── base.go                  # Shared BaseAgent functionality
│   │   ├── test_runner.go           # TestRunner agent
│   │   ├── ops_guard.go             # OpsGuard agent
│   │   ├── data_trace.go            # DataTrace agent
│   │   ├── task_master.go           # TaskMaster agent
│   │   ├── skill_builder.go         # SkillBuilder agent
│   │   ├── env_manager.go           # EnvManager agent
│   │   ├── api_probe.go             # APIProbe agent
│   │   ├── metrics_collector.go     # MetricsCollector agent
│   │   ├── security_scanner.go      # SecurityScanner agent
│   │   └── ui_discovery.go          # UIDiscovery agent (Playwright crawl, SPA routes, elements)
│   ├── chat/
│   │   ├── manager.go               # Chat session management, message handling
│   │   ├── orchestrator.go          # Skill orchestration, context assembly, LLM interaction
│   │   ├── router.go                # Router Agent — intent detection, model capability registry
│   │   └── types.go                 # Session, Message, Attachment, SkillInfo types
│   ├── llm/
│   │   └── client.go                # LLM provider abstraction (OpenAI, Azure, Ollama, Anthropic, Custom)
│   ├── store/
│   │   └── store.go                 # File-based JSON persistence (skills, workflows, chat, discovery)
│   ├── workflow/
│   │   ├── workflow.go              # Workflow execution engine
│   │   └── templates.go             # Built-in workflow templates
│   ├── skills/
│   │   ├── skills.go                # Registry, Executor, Validator
│   │   └── secret_resolver.go       # Vault reference resolution
│   ├── dbdrivers/
│   │   └── drivers.go               # Database driver abstraction (Postgres, MySQL, Oracle, SQLServer, SQLite)
│   ├── confluence/
│   │   ├── client.go                # Confluence REST API client
│   │   └── discovery.go             # Confluence space/page discovery
│   ├── jira/
│   │   ├── client.go                # Jira REST API client (search, issues, comments)
│   │   └── discovery.go             # Jira project/issue discovery
│   ├── gitclient/
│   │   └── runner.go                # GitHub API client (repos, PRs, commits, issues, files)
│   ├── kubectl/
│   │   └── runner.go                # Kubernetes CLI wrapper (namespaces, pods, logs, contexts)
│   ├── discovery/                   # Integration metadata discovery cache
│   └── utils/
│       ├── httpclient.go            # Proxied HTTP client with retry + timeout
│       └── audit.go                 # Append-only JSONL audit log
└── frontend/
    ├── package.json                 # npm scripts: dev, build, preview, check
    ├── vite.config.ts               # Vite + Svelte plugin config
    ├── tsconfig.json                # TypeScript configuration
    ├── index.html                   # HTML entry point
    ├── src/
    │   ├── main.ts                  # Svelte mount point
    │   ├── App.svelte               # Root shell — sidebar + view switching
    │   ├── types.ts                 # TypeScript types mirroring Go structs
    │   ├── style.css                # Global dark theme (slate/blue palette)
    │   └── lib/
    │       ├── Dashboard.svelte     # Stats, agent status, event stream
    │       ├── ChatPanel.svelte     # AI chat — sessions, skills, Ask/Deep Research modes
    │       ├── FlowGraph.svelte     # D3 + Dagre real-time flow graph
    │       ├── MindMap.svelte       # D3 hierarchical tree (Workflows + Integrations)
    │       ├── AgentsPanel.svelte   # Agent cards with status
    │       ├── InvestigationDashboard.svelte  # Start/view investigations
    │       ├── WorkflowPanel.svelte # Workflow editor + runner + run history
    │       ├── DiscoveryPanel.svelte # UI discovery wizard (crawl, elements, tests)
    │       ├── LogViewer.svelte     # Kubernetes pod log viewer
    │       ├── CredentialManager.svelte       # Encrypted credential CRUD
    │       ├── SkillsPanel.svelte   # Skill registry browser + AI generator
    │       ├── SettingsPanel.svelte  # Settings tabs (LLM, Proxy, Auth, Agents, etc.)
    │       ├── SetupWizard.svelte   # First-run setup wizard (5 steps)
    │       ├── UserGuide.svelte     # In-app searchable documentation
    │       └── Sidebar.svelte       # Navigation sidebar
    └── wailsjs/                     # Auto-generated Go↔JS bindings (do not edit)

Discovery (UI Crawl & Element Detection)

The Discovery panel provides automated web application crawling with deep element detection:

• Guided Wizard — 5-step flow: Configure → Crawl → Select Pages → Element Discovery → Review & Save
• SSO Authentication — Adaptive 3-phase login handles Microsoft Entra, PingFederate, Okta, ADFS, Keycloak (single-page and federated flows)
• SPA Route Discovery — Clicks navigation elements, intercepts JS bundle route definitions, monitors history.pushState/replaceState, supports hash-based routing
• Base Path Filtering — Crawler stays within the URL path prefix (e.g. only /myapp/portal/*)
• Element Detection — Buttons, inputs, forms, ARIA roles, panels, cards, tabs, modals, nav/header/footer
• Screenshots — Captures JPEG screenshot per page
• Session Reuse — Multi-page element discovery uses a single browser session with one SSO login
• Show Browser — Non-headless mode to watch SSO flow live for debugging
• Confluence Support — Discover wiki pages via REST API
• Test Generation — Auto-generates test cases from discovered elements

Powered by Playwright for browser automation.

Chat & LLM Integration

The Chat panel is the primary AI interface, backed by configurable LLM providers:

Chat Modes:

• Ask — Single-turn Q&A with live skill context (Kubernetes, DB, Jira, GitHub, Confluence, etc.)
• Deep Research — Multi-step investigation: LLM generates a plan → each step executes against live integrations → synthesized report
• Agent — Autonomous multi-step reasoning with tool calls and iterative refinement

Skills (toggleable per session): Kubernetes, Database, GitHub, Jira, Confluence, API, Security, Metrics, General

Router Agent & Unified Multimodal Chat

The Chat panel provides a single unified input for text, image, audio, and video generation. There are no separate media buttons — the Router Agent automatically detects your intent:

1. Automatic Intent Detection — As you type, the Router Agent analyzes your prompt using 15+ pattern matchers and classifies it as text, image, video, or audio
2. Smart Model Selection — When a media intent is detected, a banner slides in above the input showing:
   • Detected intent type (🎨 Image / 🎬 Video / 🎵 Audio) with confidence percentage
   • A model dropdown auto-populated with only compatible models from your LLM profiles and media configuration
   • ⚙ expandable options panel for advanced settings (size, quality, voice, speed, etc.)
   • ✕ dismiss button to force text mode
3. No Models Warning — If no models are configured for the detected intent, the banner shows a clear warning
4. Seamless Send — Press Enter and the unified send pipeline routes your prompt to the correct generation backend (text LLM, DALL-E/GPT-Image, TTS, or video model)

How intent detection works:

• Image triggers: "generate image", "draw", "create a picture", "design a logo", etc.
• Video triggers: "generate video", "create animation", "make a clip", etc.
• Audio triggers: "generate audio", "text to speech", "read this aloud", "create voiceover", etc.
• Everything else defaults to text with 100% confidence

The Router Agent's model capability registry maps known model patterns (dall-e → image, whisper → STT, tts → audio, sora → video, gpt-4/claude → text) and cross-references your configured profiles.

Multi-Instance Resources

SquadLogic supports multiple instances of the same resource type:

All instances are queried when the corresponding Chat skill is active. Results are labeled by instance name.

Data Storage

All persistent data is stored under ~/.squad_logic/ (configurable via Settings):

Prerequisites

• Go >= 1.23 (tested with 1.26)
• Node.js >= 18 (22 LTS recommended — see frontend/.nvmrc)
• Wails CLI v2: go install github.com/wailsapp/wails/v2/cmd/wails@latest
• Playwright (for UI Discovery): npm install playwright (in project root or globally)

macOS Additional

# Xcode command line tools (for CGO / WebView)
xcode-select --install

Verify Prerequisites

go version          # go1.23+
node --version      # v18+ (v22 recommended)
wails doctor        # checks all Wails dependencies

Quick Start

# 1. Clone the repository
git clone <repo-url> && cd SquadLogic

# 2. Install frontend dependencies
cd frontend && npm install && cd ..

# 3. Run in development mode (hot reload)
wails dev

# 4. Or build for production
wails build

# 5. Launch the built app (macOS)
open build/bin/squadlogic-app.app

Development

Live Development

# Start with hot reload — Go backend rebuilds on save, Vite HMR for frontend
wails dev

# Frontend is also accessible at http://localhost:34115 in a browser (for devtools)

Build Commands

# Production build for current platform
wails build

# Go-only build check (no frontend, faster)
go build ./...

# Frontend only
cd frontend && npm run build

# Type checking
cd frontend && npm run check

macOS Build (arm64)

# Build native macOS .app bundle
wails build

# Output: build/bin/squadlogic-app.app (26 MB)

# Launch
open build/bin/squadlogic-app.app

Windows Build (amd64)

Cross-compile from macOS (no Windows machine required):

# Build Windows .exe from macOS
wails build -platform windows/amd64

# Output: build/bin/squadlogic-app-amd64.exe (28 MB, PE32+ GUI x86-64)

Note: Windows cross-compilation uses Go's built-in cross-compile support. No CGO dependencies are needed for the Windows target, so no additional toolchain is required.

Build Both Platforms

# Build macOS first, then Windows
wails build && wails build -platform windows/amd64

# Verify outputs
ls -lh build/bin/squadlogic-app.app build/bin/squadlogic-app-amd64.exe

Project Conventions

• Go backend (app.go) — All func (a *App) ExportedMethod(...) methods are auto-bound to the frontend via Wails. The wailsjs/ directory is regenerated on build. Includes approval gate APIs (ApproveJob, RejectJob, GetPendingApprovals), kill switch APIs (KillJob, KillInvestigation), and daemon scheduler APIs (ListDaemonTasks, AddDaemonTask, RemoveDaemonTask).
• Frontend — Each panel is a self-contained .svelte component in frontend/src/lib/. State is local to each component; cross-component communication uses the Wails event system.
• Configuration — All config structs live in internal/config/config.go. JSON tags define the config file format. Never store secrets in config — use vault credential references (*_ref fields).
• Agents — Each agent implements the Agent interface defined in internal/core/types.go. Add new agents in internal/agents/ and register them in app.go:registerAgents().
• Skills — Stored as JSON in ~/.squad_logic/skills/. Can be created manually, generated via AI, or built by the SkillBuilder agent.

Adding a New Agent

1. Create internal/agents/my_agent.go implementing the Agent interface
2. Add a constructor function: func NewMyAgent(eventBus *core.EventBus, deps *Deps) *MyAgent
3. Register in app.go:registerAgents(): a.supervisor.Register(agents.NewMyAgent(...))
4. Add enable/disable toggle in config.AgentsConfig struct
5. The agent appears automatically in the Agents panel and is available for investigations

Adding a New Frontend Panel

1. Create frontend/src/lib/MyPanel.svelte
2. Import and add a route case in App.svelte ({:else if currentView === 'mypanel'})
3. Add entry in Sidebar.svelte navigation items array
4. Call Go backend via auto-generated bindings: import { MyMethod } from '../../wailsjs/go/main/App'

Go ↔ Frontend Binding

Wails auto-generates TypeScript bindings for all exported App methods:

Go: func (a *App) GetK8sPods(namespace string) ([]map[string]interface{}, error)
 ↓  auto-generated  ↓
TS: import { GetK8sPods } from '../../wailsjs/go/main/App'
    const pods = await GetK8sPods('default')

Rules:

• Only methods on the *App struct with exported names are bound
• Parameters and return types must be JSON-serializable
• The wailsjs/ directory is auto-regenerated — never edit it manually

Event System

The Go backend emits events via core.EventBus. The frontend subscribes using Wails runtime:

// Go — emit event
a.eventBus.Publish("agent:status", map[string]string{"agent": "OpsGuard", "status": "running"})

// Svelte — subscribe
import { EventsOn } from '../../wailsjs/runtime/runtime'
EventsOn('agent:status', (data) => { /* update UI */ })

Configuration

Configuration lives in ~/.squad_logic/config.json. On first launch, the Setup Wizard creates it. All fields have sensible defaults.

Full Configuration Reference

{
  "app_name": "SquadLogic",
  "data_dir": "~/.squad_logic",
  "log_level": "info",
  "mode": "desktop",

  "proxy": {
    "url": "http://your.proxy:8080",
    "insecure_skip_tls": false
  },

  "llm": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key_ref": "openai-key",
    "base_url": ""
  },

  "auth": {
    "default_provider": "entra",
    "entra": {
      "tenant_id": "your-tenant-id",
      "client_id": "your-client-id",
      "redirect_uri": "http://localhost:9090/callback",
      "scopes": ["openid", "profile", "email"]
    },
    "keycloak": {
      "server_url": "https://keycloak.example.com",
      "realm": "your-realm",
      "client_id": "your-client-id"
    },
    "generic": {
      "issuer_url": "https://issuer.example.com",
      "client_id": "your-client-id"
    }
  },

  "agents": {
    "test_runner": true,
    "ops_guard": true,
    "data_trace": true,
    "task_master": true,
    "skill_builder": true,
    "env_manager": true,
    "api_probe": true,
    "metrics_collector": true,
    "security_scanner": true,
    "ui_tester": true
  },

  "kubernetes": {
    "kubeconfig_path": "~/.kube/config",
    "context": "my-cluster",
    "default_namespace": "default"
  },

  "database": {
    "connections": [
      {
        "name": "staging-postgres",
        "driver": "postgres",
        "host": "db.staging.internal",
        "port": 5432,
        "username": "app_user",
        "pass_ref": "staging-db-pass",
        "database": "myapp",
        "ssl_mode": "require",
        "read_only": true
      }
    ]
  },

  "github": {
    "api_url": "https://api.github.com",
    "repo": "org/repo",
    "pat_ref": "github-pat"
  },

  "jira": {
    "url": "https://company.atlassian.net",
    "project_key": "PROJ",
    "username": "[email protected]",
    "api_key_ref": "jira-token"
  },

  "confluence": {
    "url": "https://company.atlassian.net/wiki",
    "space_key": "ENG",
    "jira_ref": "default"
  },

  "prometheus": {
    "url": "http://prometheus:9090"
  },

  "targets": {
    "services": [
      {
        "name": "user-api",
        "base_url": "https://api.staging.example.com",
        "health_path": "/healthz"
      }
    ]
  },

  "environments": [
    {
      "name": "staging",
      "description": "Staging environment",
      "variables": { "BASE_URL": "https://staging.example.com" },
      "credentials": ["staging-db-pass", "staging-api-key"]
    }
  ]
}

Vault Credential References

Fields ending in _ref (e.g. api_key_ref, pass_ref, pat_ref) reference credentials stored in the encrypted vault. This way secrets never appear in config files.

config.json:   "api_key_ref": "my-jira-token"
                     ↓
vault lookup:  vault/my-jira-token → (decrypted value at runtime)

Environment Variables

Troubleshooting

macOS — "app is damaged and can't be opened":

This happens because the app isn't code-signed. macOS Gatekeeper adds a quarantine attribute, especially when the .app is shared via Teams, Slack, email, or browser download.

# Remove quarantine attribute
xattr -cr build/bin/squadlogic-app.app

# Then launch normally
open build/bin/squadlogic-app.app

If the recipient downloaded the app elsewhere (e.g. ~/Downloads):

xattr -cr ~/Downloads/squadlogic-app.app

Build fails with CGO errors:

# macOS — install Xcode command line tools
xcode-select --install

wails dev hangs or frontend doesn't load:

cd frontend && npm install  # ensure deps are installed
wails doctor                # diagnose missing deps

Corporate proxy — TLS errors:

• Set proxy.insecure_skip_tls: true in config
• The app auto-sets GODEBUG=x509negativeserial=1 for Go 1.23+ corporate proxy compatibility

Playwright not found (Discovery fails):

# Install Playwright in the project root
npm install playwright
# Or globally
npm install -g playwright

Node.js version mismatch:

# If using nvm:
nvm use 22
# Or set PATH explicitly before building:
export PATH="$HOME/.nvm/versions/node/v22.20.0/bin:$PATH"
wails build

Frontend TypeScript errors:

cd frontend && npm run check

Go build errors:

go build ./...               # compile check
go vet ./...                 # static analysis

License

MIT License — see LICENSE for details.

Current Version: 0.9.4

Build Both macOS and Windows Binaries

# Build both macOS and Windows binaries (requires Node.js 22+ and Wails prerequisites)
nvm use 22 && wails build -clean -platform darwin/arm64,windows/amd64

# Outputs:
#   build/bin/squadlogic-app.app/Contents/MacOS/squadlogic-app   (macOS)
#   build/bin/squadlogic-app-amd64.exe                          (Windows)