Modern Docker Management, Designed for Everyone
Arcane agent guide
Arcane is a Docker management platform with a Go backend, SvelteKit frontend, headless agent modes, and a Cobra CLI.
Rules that apply to every change
Follow AI_POLICY.md, including its maintainer exemption. Outside contributors must disclose AI assistance and meet the policy's development and human verification requirements.
- Never run state-changing Git commands. Do not stage, commit, push, tag, stash, create branches, or create worktrees.
- For maintainer work, do not start, restart, or rebuild the development stack unless the user explicitly asks.
- Search the owning domain and existing helpers before adding functions, services, API clients, components, or utilities. Update existing logic and its callers directly.
- Do not add stubs, compatibility shims, pass-through wrappers, or duplicate implementations. Call existing helpers directly.
- Add tests only for new functionality. For bug fixes and refactors, update existing tests when needed and run relevant existing coverage. Do not add regression tests.
- Never add handler tests. Test new business behavior at the service layer or in its owning logic package. Preserve existing handler tests.
- After every change, including documentation changes, run
just format all, thenjust lint all. Fix every issue and keep the formatter's output. - Report what you verified and any blockers. Never claim manual verification that did not happen.
Keep changes focused
New functionality belongs in the domain that owns it. Keep each file focused on one clear responsibility. Do not create god files in services, components, or CLI commands.
Use the standard domain file set and move substantial child features into children/<feature>/. Split code by responsibility rather than a fixed line count. Avoid trivial packages, unnecessary abstractions, and unrelated restructuring.
Keep comments short. If the structure needs a paragraph to explain it, simplify the code.
Avoid nested or chained ternary expressions unless absolutely necessary. Prefer if/else or switch for conditional logic with multiple branches.
Go imports and shared code
- Use default Go import names. Add an alias only to resolve an actual naming conflict.
- Put public and shared Go contracts in the top-level
types/module. Keep persistence models in their owning domain. - Put reusable helper utilities in the appropriate package under
backend/pkg/utils/.
Repository layout
The Go workspace contains three modules:
backend/ Go application, HTTP API, domain logic, jobs, and embedded frontend
cli/ Cobra CLI and its API client
types/ Public domain and API contracts shared by backend and CLI
The frontend lives in frontend/. End-to-end tests live in tests/.
Backend
The backend is organized by domain. Each domain owns its behavior and routes.
backend/
├── cmd/ process entrypoint
├── api/ API assembly and exceptional HTTP/stream/WebSocket routes
├── internal/
│ ├── <domain>/ module, routes, business logic, and persistence models
│ ├── bootstrap/ application lifecycle, router, jobs, and startup wiring
│ ├── di/ Fx dependency graph and providers
│ ├── config/ environment configuration
│ ├── database/ database setup and shared persistence primitives
│ └── middleware/ authentication, authorization, and environment proxying
├── pkg/ reusable engines, infrastructure, and helpers
├── resources/ migrations, email templates, and runtime assets
└── frontend/ embedded frontend build
Domain files
Use these files under backend/internal/<domain>/:
module.go: composition and route registrationservice.go: business operations and orchestrationmodel.go: persistence modelshandler.go: HTTP input and outputhelpers.go: package-local helpers with a clear purpose
Create a file only when it has a real responsibility. Do not add placeholders.
Child features and import boundaries
Place substantial features under <domain>/children/<feature>/ and use the same standard file set. The children/ directory itself must contain no Go files.
Only a child package's immediate parent may import it. Siblings, higher-level ancestors, other domains, DI, bootstrap, and API assembly must use the parent's API. Apply this boundary recursively.
Children must not import their parent. The parent coordinates interactions between children and keeps child instances private. Image patching belongs under image/children/patch. System recovery backups belong under system/children/backup, with snapshots and system-managed volumes beneath that feature.
Do not expose child types through parent API signatures or inject child instances into outside packages. Keep shared persistence models in the parent's model.go and shared contracts in the top-level types/ module.
Filenames and test pairing
Production filenames must be single words without underscores. Build-tagged files may append their tag:
service_playwright.go
service_buildables.go
helpers_unix.go
Use helpers_nonunix.go for a !unix implementation.
Tests belong beside the production file they cover. Use the exact production basename followed by _test.go:
service.go → service_test.go
service_playwright.go → service_playwright_test.go
Never create a production file just to justify a test filename.
These layout rules apply to business domains and their children. The filename policy excludes:
- Infrastructure packages:
bootstrap,common,config,database, anddi backend/pkg- CLI packages
- Shared types
Middleware uses descriptive, single-word production filenames such as cors.go, csrf.go, and environment.go, with the same exact test-file pairing.
Wiring and API assembly
Wire dependencies in internal/di.
Keep startup order, lifecycle hooks, database migration wiring, and router assembly in internal/bootstrap.
The remaining api/ code handles API assembly, diagnostics, streams, WebSockets, and webhook dispatch. Ordinary REST endpoints belong in their domains. Do not expand api/handlers into a central handler layer or recreate a global internal/services or models package.
HTTP and business logic
Use Echo v5 as the router and Huma v2 for typed REST/OpenAPI operations. Register permissioned endpoints with middleware.RegisterWithPermission.
Direct Echo routes are reserved for:
- WebSockets and streams
- Diagnostics and webhooks
- Playwright support
- The environment proxy
- Embedded frontend delivery
Handlers translate typed HTTP data and call services. They must not contain business logic. Services receive dependencies through constructors/Fx.
Use:
slogfor structured logging- Standard
errorsandfmt.Errorf("…: %w")for error handling and wrapping internal/common.Classifyfor semantic errorstypes/base.FieldErrorfor validation fields
Existing helpers
Before adding backend logic, search the owning domain and the relevant shared packages:
go.getarcane.app/docker(Kit): Docker names, labels, clients, logs, and stream helpersbackend/pkg/projects: Compose parsing, discovery, and image referencesbackend/pkg/pagination: in-memory and database paginationbackend/pkg/libarcane: reusable Arcane engines and transport behaviorbackend/pkg/utils: shared infrastructure utilities
Persistence
Use database.BaseModel and existing database helpers where appropriate. Reuse GORM relationships and Preload.
Keep persistence models separate from the public API contracts in types/.
CLI and shared types
cli/
├── main.go CLI entrypoint
├── pkg/ Cobra root and domain command packages
└── internal/
├── client/ shared API client
├── config/ CLI configuration
├── cmdutil/ command support
├── output/ output rendering
└── ... prompts, runtime state, and other internal support
types/ shared domain and API contracts, grouped by domain
Update existing commands and reuse the CLI client, configuration, and output code.
Keep commands focused on input, API calls, and output. Backend business behavior belongs in its owning backend domain.
Shared contracts in types/ must remain independent of backend persistence and application wiring.
Frontend
The frontend uses SvelteKit v3 and Svelte 5. Configuration lives in frontend/vite.config.ts.
frontend/src/
├── routes/ SvelteKit pages and layouts
└── lib/
├── components/ shared UI components
├── config/ navigation and access-surface configuration
├── hooks/ reusable reactive behavior
├── layouts/ shared layout components
├── query/ shared query keys
├── paraglide/ generated message code
├── services/ API clients extending BaseAPIService
├── stores/ rune-based application state
├── types/ frontend-only TypeScript types
└── utils/ frontend utilities
Components and state
- Use Svelte 5 runes:
$props,$state,$derived, and$effect. - Do not use
export let,$:,on:event,$$props,$$restProps, or legacy slots. - Extend
BaseAPIServiceand reuse existing services and query/mutation patterns. - Use precise TypeScript types. Do not introduce
any. - Reuse shared components before creating page-local variants.
Error handling
Component error paths must do more than call console.error:
- For one-shot actions, use
handleApiResultWithCallbacks. - Where a
Resultdoes not fit, such as TanStackonError, usetoast.error(headline, { description: extractApiErrorMessage(err) }). - For streams and polling feeds, show an inline unavailable state where the data renders.
- For page loads, rethrow through
throwPageLoadError.
A thrown APIError.message already contains the server's message. Surface that message rather than showing only a canned string.
Translations
- Put every rendered string behind Paraglide messages.
- Reuse a matching key from
frontend/messages/en.jsonbefore adding one. - Add new keys only to
en.json. Crowdin manages every other locale. - Generate Paraglide output through the existing tooling. Do not edit generated files by hand.
Environments and authorization
Environment-scoped behavior
- Environment ID
"0"is the local Docker environment. - Environment-scoped API paths use
/environments/{id}/.... - Await
environmentStore.readyorgetCurrentEnvironmentId()before making requests. - Redirect environment-specific detail pages when the selected environment changes.
Permissions
Backend permission middleware is authoritative. Frontend gates are for user experience only.
Keep the permission catalog, access-surface registry, and frontend navigation gates as separate layers.
Determine global admin status through PermissionSet.IsGlobalAdmin() or the user DTO's isGlobalAdmin. Never infer it from a role ID.
Runtime modes and jobs
- Manager mode serves the UI and manages environments.
- Direct agent mode uses
AGENT_MODE=trueand accepts manager connections. - Edge agent mode uses
EDGE_AGENT=truewithMANAGER_API_URLand dials the manager.
Background jobs implement the scheduler job contract. Wire them through internal/di and register them in internal/bootstrap/jobs_bootstrap.go.
Multi-step, fan-out, or resumable jobs use backend/pkg/scheduler/flow: Francis workflows that run inside coordinator runs. Follow the migration recipe in its package doc. Steps are idempotent service methods, the last step returns scheduler.Outcome, the job registers a flow.Job, and flowtest.AssertDefinitions guards version bumps. Keep single-operation jobs as ordinary jobs.
Validation
Tests
Adding tests and running tests are separate decisions. The new-functionality-only rule does not remove the need to verify changes.
Run the narrowest relevant existing coverage for the changed behavior, then choose the appropriate repository test target:
just test backend
just test cli
just test types
Use just test e2e for browser coverage when the required environment is available. just test all includes E2E tests and requires their prerequisites.
Do not start a development stack implicitly to satisfy a test target. Documentation-only changes do not require adding tests.
Required checks
After every change, including documentation changes, run these commands in order:
just format all
just lint all
Fix every reported issue and retain the formatter's output.
Report what ran, what passed, and anything you could not verify. Outside contributions must also meet the development and human testing requirements in AI_POLICY.md before submission.