Project Structure

Project Structure

How strut is organized on disk — the engine installation at ~/.strut/, the user project layout, and what each module is responsible for.

Engine (~/.strut/)

strut                  CLI entrypoint — command dispatch, usage, argument parsing
VERSION                Semver version (read by strut --version)
install.sh             One-liner installer (clone + symlink + upgrade + uninstall)

lib/
├── config.sh          Project config discovery (find_project_root, load_strut_config)
├── registry.sh        Pluggable registry auth (ghcr/dockerhub/ecr/none)
├── utils.sh           Colors, logging, SSH helpers, compose builders
├── deploy.sh          Deploy orchestration, VPS release, repo sync
├── health.sh          Dynamic health checks from services.conf
├── docker.sh          Docker pull, prune helpers
├── schema.sh          Database schema management
├── volumes.sh         Dynamic volume management from volume.conf
├── logs.sh            Log viewing and management
├── local.sh           Local development environment
├── debug.sh           Container debugging tools
├── audit.sh           VPS audit system
├── migrate.sh         VPS migration wizard orchestration
├── monitor.sh         Monitoring stack management
├── github-token.sh    GitHub token helpers
│
├── cmd_deploy.sh      Deploy/release/update command handler
├── cmd_stop.sh        Stop command handler
├── cmd_backup.sh      Backup command handler
├── cmd_db.sh          Database operations (schema, pull, push)
├── cmd_drift.sh       Drift detection command handler
├── cmd_logs.sh        Logs command handler
├── cmd_debug.sh       Debug command handler
├── cmd_local.sh       Local development command handler
├── cmd_domain.sh      Domain/SSL command handler
├── cmd_volumes.sh     Volume management command handler
├── cmd_keys.sh        Key management command handler
├── cmd_remote.sh      Shell/exec/status command handler
├── cmd_init.sh        Init command handler
├── cmd_scaffold.sh    Scaffold command handler
├── cmd_skills.sh      AI agent skills command handler
│
├── backup/            Database-specific backup implementations
│   ├── mysql.sh       MySQL backup/restore
│   ├── sqlite.sh      SQLite backup/restore
│   ├── alerts.sh      Backup alerting
│   ├── compare.sh     Backup comparison
│   ├── health.sh      Backup health scoring
│   ├── retention.sh   Backup retention management
│   ├── schedule.sh    Backup scheduling
│   └── verify.sh      Backup verification
│
├── drift/             Drift detection modules
│   ├── alerts.sh      Drift alerting
│   ├── autofix.sh     Auto-fix logic
│   ├── metrics.sh     Drift metrics
│   └── schedule.sh    Drift scheduling
│
├── keys/              Key management modules
│   ├── api.sh         API key management
│   ├── audit.sh       Key audit logging
│   ├── db.sh          Database password rotation
│   ├── discovery.sh   Secret discovery
│   ├── env.sh         Env var management
│   ├── github.sh      GitHub secrets sync
│   ├── pull.sh        Key pull operations
│   ├── ssh.sh         SSH key management
│   ├── status.sh      Key status reporting
│   └── test.sh        Key testing
│
└── migrate/           VPS migration wizard phases
    ├── phase-preflight.sh   Phase 1: Pre-flight checks
    ├── phase-setup.sh       Phase 2: Setup strut on VPS
    ├── phase-audit.sh       Phase 3: Audit
    ├── phase-generate.sh    Phase 4: Generate stacks
    ├── phase-backup.sh      Phase 5: Pre-cutover backup
    ├── phase-test.sh        Phase 6: Test deployment
    ├── phase-cutover.sh     Phase 7: Cutover
    ├── phase-cleanup.sh     Phase 8: Cleanup
    ├── github-auth.sh       GitHub authentication helpers
    ├── setup-repo.sh        Repository setup
    └── ssh-helpers.sh       SSH helper functions

templates/             Stack scaffolding templates
├── Dockerfile
├── docker-compose.dev.yml
├── docker-compose.prod.yml
├── docker-entrypoint.sh
├── env.template
├── services.conf.template
├── strut.conf.template
├── dev.sh
└── .github/           CI/CD workflow templates

tests/                 BATS test suite
├── test_helper/
│   └── common.bash    Shared test helpers
├── test_config.bats
├── test_registry.bats
├── test_health_discovery.bats
├── test_init.bats
├── test_scaffold.bats
├── test_docker_helpers.bats
├── test_utils.bats
├── test_volumes.bats
├── test_drift_helpers.bats
├── test_schema_helpers.bats
├── test_no_hardcodes.bats
└── ...

User Project

my-project/
├── strut.conf              # Project-level config
├── .prod.env               # Production secrets (gitignored)
├── .staging.env            # Staging secrets (gitignored)
└── stacks/
    └── my-app/
        ├── docker-compose.yml
        ├── docker-compose.local.yml
        ├── .env.template
        ├── services.conf
        ├── required_vars
        ├── volume.conf
        ├── repos.conf
        ├── backup.conf
        ├── .drift-ignore
        ├── nginx/
        ├── sql/init/
        └── config/