See the README and per-package AGENTS.md files for full architecture details. Essentials:
- Bun 1.3+, Go 1.24+, Docker
bun install— install all JS/TS dependenciesdocker compose up -d— start Postgres, miniKMS, OpenFGA, Atrium, Mailpit- Atrium is the pinned image
ghcr.io/bravo68web/atrium:0.2.0-rc.17. Dev mountsdocker/atriumfor config and branding. bun run cli:init— bootstrap RustFS and Atrium clientsbun run cli create-dev-user --seed— seed a development user
- Fork the repo and create a branch from
main(or from the active program track branch when working on the no-piggyback rollout — see below) - Branch naming:
feat/,fix/,chore/,docs/ - Keep PRs focused — one feature or fix per PR
- Push and open a PR against
main(or the program track branch when directed) - Use the PR template no-piggyback + org-create channel checks
When working on tenancy, deploy CLI split, manage surface, licensing, or FE edition isolation:
- Track:
feat/the-big-update(phase branches as needed) - Product matrix: EDITIONING.md, deploy all editions: DEPLOY.md, root AGENTS.md
- Local planning notes may live under
docs/(gitignored — not required for OSS clone)
Local defaults favor Hosted-like development. That is intentional — and easy to misread as production self-host config.
| Variable | Default / missing behavior | Footgun |
|---|---|---|
ENVSYNC_EDITION |
Defaults to enterprise in env.ts |
An “OSS” mental model still loads enterprise edition flags unless you set ENVSYNC_EDITION=oss. |
ENVSYNC_DEPLOYMENT_MODE |
Optional. If unset: OSS → selfhosted; enterprise → hosted |
Self-host enterprise installs that omit the var behave as Hosted (multi-org SaaS policy, license bypass for multi-org). Always set ENVSYNC_DEPLOYMENT_MODE=selfhosted for self-host. |
| Hosted FE build | CF deploy-fe must use build:hosted |
Never point Hosted Cloudflare at build:oss — EE dashboard modules will be empty stubs. |
| Org create API | POST /auth/create-organization only |
Do not reintroduce /auth/create-workspace. |
Self-host checklist:
ENVSYNC_DEPLOYMENT_MODE=selfhosted
ENVSYNC_EDITION=oss # or enterprise for licensed EE
# EE self-host also needs entitlement verify + setup token / deploy CLI for org createSee EDITIONING.md and SELFHOSTING.md (enterprise license install notes for self-host).
Every API change must include:
- Mock test in
tests/mock/{feature}.test.ts(unit-level, mocked Vault/DB/FGA) - E2E test in
tests/e2e/flows/{feature}.e2e.test.ts(real services via Docker)
Run both suites locally before pushing:
bun run test:mock
bun run test:e2eUse bun run test:e2e from the repo root. It runs e2e-setup init before invoking the package E2E suite.
- Zod validator in
src/validators/{resource}.validator.ts(include.openapi()annotations) - Service method in
src/services/{resource}.service.ts(static methods, Kysely queries) - Controller in
src/controllers/{resource}.controller.ts(delegates to service, handles errors, logs audit) - Route in
src/routes/{resource}.route.ts(usedescribeRoute,zValidator, permission middleware) - Register the route in
src/modules/core-modules.ts - Add mock test + E2E test (as above)
- File naming:
{resource}.controller.ts,{resource}.service.ts,{resource}.route.ts,{resource}.validator.ts - New env vars: add to the base Zod schema in
src/utils/env.tsor to a module env extension - Database changes: add a Kysely migration in
src/libs/db/migrations/, run withbun run db - Formatting:
prettier --write .(uses@bravo68web/prettier-config)
| Location | Convention | Example |
|---|---|---|
src/pages/ |
PascalCase directory per feature | Applications/ |
src/components/{feature}/ |
PascalCase files | AppCard.tsx |
src/components/ui/ |
kebab-case (shadcn — don't hand-edit) | button.tsx |
src/api/ |
React Query hooks | {resource}.api.ts |
src/hooks/ |
Custom React hooks | useDebounce.ts |
src/contexts/ |
Context providers | AuthContext.tsx |
- Use
@envsync-cloud/envsync-ts-sdkfor API types — don't duplicate types locally - Server state via React Query, client state via React Context
- Only
VITE_*env vars are exposed to the client - Register new dashboard routes and nav items via
src/modules/core-modules.ts - Run
bun run lintbefore pushing
EnvSync is a public dual-license monorepo (not private-superset-only). See:
- LICENSE — MIT default + proprietary carve-out
- EDITIONING.md — product matrix and package graph
- SELFHOSTING.md — self-host deploy / org bootstrap
Code under packages/envsync-enterprise, packages/envsync-enterprise-web,
packages/envsync-enterprise / envsync-enterprise-web, and packages/deploy-cli (enterprise deploy)
is proprietary. By contributing to those paths you grant EnvSync Cloud the
right to use, modify, and distribute your contribution under the EnvSync
Enterprise License (and to relicense as needed for the product).
MIT-path contributions remain under MIT.
- Do not add proprietary packages as production dependencies of MIT packages
(CI:
bun run check:boundaries).envsync-enterprise-webis a devDependency ofenvsync-web(Vite resolves it only for enterprise/hosted builds). - Do not reintroduce
apps/envsync-management-web,envsync-management-api, orsdks/envsync-management-*. - Do not reintroduce monorepo spawn shims for OSS deploy.
- Prefer Organization in user-facing copy; org create API is
POST /auth/create-organizationonly. - Self-host multi-org limits come from entitlement claims; do not rely on
bare
ENVSYNC_MAX_ORGS(support override only). - Shared extension seams live in API/web module loaders; keep core shells free of EE imports.
- Shared design tokens live in MIT
envsync-ui— do not fork:root/.darkblocks in apps.
- Command definition in
internal/features/commands/{feature}_commands.go - Action handler in
internal/actions/{domain}.go - Service logic in
internal/services/{domain}.go(interface + implementation) - Repository (API client) in
internal/repository/if new API calls are needed - Domain models in
internal/domain/if new types are needed - Presentation formatting in
internal/presentation/if new table output is needed
- All internal packages live under
internal/(unexported by Go convention) - File naming: snake_case (
{feature}_commands.go,{domain}.go) - Run
make lint(golangci-lint) andmake tidybefore pushing
SDKs are auto-generated — do NOT edit files in sdks/envsync-ts-sdk/src/ or sdks/envsync-go-sdk/sdk/.
To update SDKs after API changes:
- TypeScript:
bun run generate:local - Go:
./generator.sh
All PRs must pass these GitHub Actions jobs (.github/workflows/ci.yaml):
| Job | What it runs |
|---|---|
| build | bun run build (all packages) |
| test-mock | Mock/unit tests against a Postgres service container |
| test-e2e | Full integration tests with Postgres, miniKMS, OpenFGA, Atrium, Mailpit |
Use Conventional Commits:
feat: add webhook retry logic
fix: correct env variable decryption on rollback
chore: bump dependencies
docs: update CLI usage examples
refactor: extract permission checks into middleware
test: add e2e coverage for team invitations
Keep the subject line under 72 characters.