Contributing

Setup

git clone https://github.com/VENIZIA-AI/veni-ai.git
cd veni-ai

# Install all workspace deps
bun install
cd shell/api && bun install
cd ../ui      && bun install

---

Branch naming

feature/your-feature-name
fix/issue-description
chore/what-you-are-doing
docs/what-you-are-documenting

Base all branches from develop. PRs merge back to develop.

---

Testing

Shell API — unit tests

cd shell/api
node_modules/.bin/vitest run --config vitest.unit.config.ts

Shell API — integration tests

# Requires PostgreSQL running
cd shell/api
node_modules/.bin/vitest run

Shell UI

cd shell/ui
node_modules/.bin/vitest run --reporter verbose

Use the local vitest binary

Running npx vitest from the repo root installs the wrong version. Always use node_modules/.bin/vitest directly.

---

Commit format

<type>(<scope>): <short description>

Type	When
feat	New feature
fix	Bug fix
chore	Tooling, deps, config
docs	Documentation only
test	Tests only
refactor	Code change without feature/fix

Examples:

feat(auth): add Google OAuth provider
fix(rbac): load model from cwd instead of dist
chore(deps): bump Hono to 4.12
docs(api): document exchange-keycloak endpoint

---

PR checklist

• [ ] Tests pass locally (bun run test)
• [ ] No secrets in committed files
• [ ] DB migrations added for schema changes (bun run db:migrate)
• [ ] Docs updated if API surface or config changed
• [ ] PR description explains the why, not just the what

---

Code conventions

	Rule
Services	Extend BaseService (provides logger + DI)
Validation	Zod schemas for all request bodies
DB access	Drizzle ORM only — no raw SQL
Auth	@authorize(['permission:action']) on protected endpoints
Env vars	Add to env.config.ts schema, never read process.env directly elsewhere