Coding Standards & Conventions
Relevant source files
The following files were used as context for generating this wiki page:
Barekey adheres to a strict set of coding standards and architectural conventions to maintain its "Vercel/Apple-tier DX." These standards cover TypeScript usage, Convex backend patterns, UI development with Tailwind and Shadcn, and automated agent workflows. The focus is on clarity, type safety, and a robust security model centered around envelope encryption.
Sources: AGENTS.md:3-6, AGENTS.md:126-130
TypeScript Standards
The project enforces strict TypeScript rules to ensure consistency and minimize runtime errors. Key rules include the use of specific string delimiters, semicolon termination, and naming conventions for files and types.
Core Syntax Rules
- Strings: Double quotes
""must be used for all strings and JSX props. - Statements: Semicolons
;are required on every statement. - Naming:
- Filenames use
kebab-case. - Types, classes, components, and enums use
PascalCase. - Route parameter folders use brackets (e.g.,
[org],[projectSlug]).
- Filenames use
- Enums: Standard TypeScript
enumkeywords are forbidden. Enums must be implemented asas constobjects. - Exports:
export defaultis prohibited for React components. Route files likepage.tsxandlayout.tsxmust use named exports likePage()andLayout().
Sources: AGENTS.md:113-125, pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:37
Type Safety
- Casting: Casting to
anyis strictly prohibited.unknownshould be used instead. - Collections:
- Arrays must be typed as
Array<T>. - Records must be typed as
Record<KeyType, ValueType>.
- Arrays must be typed as
- Identifiers: Document IDs must use the branded
Id<"tableName">type rather than plain strings.
Sources: AGENTS.md:121-125
Convex Backend Conventions
Convex serves as the unified backend and database layer. The project follows specific patterns for function registration, data querying, and schema management.
Function Design
Convex functions are categorized by visibility and execution environment. Public APIs (query, mutation, action) are accessible to the internet, while private logic uses internal prefixes.
| Function Type | Usage | Restrictions |
|---|---|---|
query | Public data retrieval | Must not use .filter(); use defined indexes. |
mutation | Public state changes | Use ctx.db.patch for shallow merges. |
action | Side effects / Node logic | Use "use node"; only for Node built-ins. Cannot use ctx.db. |
Sources: AGENTS.md:132-155
Query Optimization
The project forbids the use of .filter() in Convex queries. Developers must define specific indexes in schema.ts and utilize .withIndex(). Index names must explicitly list all included fields (e.g., by_orgId_and_name).
The diagram shows the standard flow for performing optimized queries in Convex using indexes.
Sources: AGENTS.md:144-148, pkg/convex/projects.ts:167-172
Architectural Policies
Slug Generation
Barekey follows a strict slug policy for organizations, users, and projects.
- Characters: Only lowercase letters
a-zand digits0-9are allowed. - Format: Hyphens, underscores, and symbols are prohibited.
- Suffixes: Numeric suffixes for uniqueness must be appended directly without separators.
Sources: AGENTS.md:37-41, pkg/convex/projects.ts:11-17
Envelope Encryption
The security model relies on a hierarchical key structure. Secrets are never stored in plaintext and are decrypted only upon explicit user request.
This sequence illustrates the process of decrypting a secret value for UI display using envelope encryption.
Sources: AGENTS.md:43-51, pkg/convex/project_variables.ts:245-283
UI and Styling Standards
The frontend is built as a React SPA using Vite, styled with Tailwind CSS and Shadcn components.
- Design Philosophy: Minimalist, fast, and obvious (Vercel/Apple-tier DX).
- Interactivity: Every interactive element must have explicit hover and focus states.
- Custom CSS: Prohibited unless absolutely unavoidable; utility classes are preferred.
- Components: Layouts must use the
OrgPageHeroandOrgSectionCardcomponents for consistency across organization and project pages.
Sources: AGENTS.md:12-16, AGENTS.md:173-176, pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:84-118
Git and Agent Workflow
Automation via AI agents is a core part of the development lifecycle. This requires specific Git practices and documentation habits.
Git Lifecycle
- Create feature branch:
feat/<task-name>. - Commit frequently with descriptive messages.
- Open PR via GitHub CLI:
gh pr create --fill. - Request review:
gh pr comment --body "@codex review". - Squash merge upon approval and resolution of critical issues.
Sources: AGENTS.md:104-111, AGENTS.md:214-232
Documentation and Comments
- JSDoc: Required for all exported functions to provide context for AI agents.
- Non-Obvious Decisions: Decisions regarding encryption, key derivation, or complex index ordering must be documented.
- Self-Evident Code: Comments that restate what the code does (e.g.,
const name = user.name) are strictly forbidden to save token context.
Sources: AGENTS.md:280-313
Conclusion
Coding standards at Barekey prioritize technical excellence through strict type safety, optimized backend queries, and a robust security architecture. By adhering to these conventions, the project ensures a high-quality developer experience and maintainable code for both human developers and autonomous agents.