Engineering Standards

This document defines the "Law of the Land" for the VENI-AI platform. Following these standards ensures consistency, security, and maintainability across the Shell and all Satellite applications.

---

1. Naming Conventions

Consistency across the stack enables automated discovery and cleaner code.

Layer	Convention	Example
Database Tables	snake_case (plural)	organization_members
Database Columns	snake_case	created_at, org_id
API Endpoints	kebab-case	/api/v1/leave-requests
JSON Keys	camelCase	{ "userId": "..." }
TypeScript Classes	PascalCase	AuthService, UserController
TypeScript Types	T + PascalCase	TUserProfile
UI Components	PascalCase	DataTable, UserMenu
UI Hooks	use + PascalCase	useAuth, useLocalStorage

---

2. Git Flow & PRs

We follow a strict Trunk-Based Development model with short-lived feature branches.

Branch Naming

• feat/feature-name — New functionality.
• fix/issue-description — Bug fixes.
• refactor/area-name — Code cleanup without behavior change.
• docs/topic-name — Documentation only.

Commit Messages

We use Conventional Commits:

• feat: add Google OAuth provider
• fix(ui): resolve white screen on mobile safari
• chore: update dependencies

---

3. Security Golden Rules

Every developer is a security engineer at VENI-AI.

1. Never Store Secrets: Never commit .env files or hardcode keys. Use the Shell's secret management.
2. Verify, Don't Trust: Always verify the RSA signature of Shell JWTs in your Satellite API.
3. Tenant Isolation: Every query must include a where(eq(table.organizationId, user.orgId)) clause unless it's a global resource.
4. Zod Validation: Every API input and environment variable must be validated using Zod.
5. Audit Everything: Use the AuditService to log destructive actions (Delete, Update, Permission changes).

---

4. API Design Patterns (REST)

• Envelope: All responses must use the standardized envelope:

  {
    "code": "RS_200",
    "data": { ... },
    "messageError": null
  }

• Stateless: The API must remain stateless. Use Redis for session data, never memory.
• Idempotency: Ensure that repeated PUT or DELETE calls result in the same state.

---

5. UI Design Patterns

• Atomic Components: Use the shared components in @shell/ui for consistency (Buttons, Inputs, Modals).
• Graceful Failure: Use the <ErrorState /> and <Loading /> components for all async operations.
• Mobile First: All Satellite UIs must be responsive and work within the Shell's mobile menu.

Enforcement

Standards are enforced via ESLint, Prettier, and CI/CD linting steps. Code that violates these standards will be rejected during the PR review.