Naming and organization

There is one way to name each thing. If you find yourself inventing a convention, use the one that exists. If the existing pattern is wrong, change it across the repo in the same PR — never leave two styles coexisting.

File names

Kind	Convention	Example
TS/JS module (non-component)	kebab-case.ts	expense-rollup.ts
React component	PascalCase.tsx	BrandMark.tsx
Next.js route file	lowercase (framework)	page.tsx, layout.tsx, route.ts
Test file	mirror source + .test.ts	pii-redaction.test.ts
Zod schema	singular, kebab-case	tax-concern.ts
Private/utility	_ prefix	_lib/, _primitives.ts

Forbidden: camelCaseFile.ts, snake_case.ts, SCREAMING.ts, plural schemas, dated suffixes (utils2.ts, helpers-new.ts).

Folders

• apps/functions/src/ — domain folders, not layers. One folder per domain (expense/, tax/, inbox/, portfolio/, family/, ca/, marketplace/, notifications/, subscription/, admin/, profile/, grievance/, ai/, kyc/ and so on). Inside: split by verb/role (callables.ts, exports.ts, lifecycle.ts). Infra in _lib/.
• packages/shared/src/schemas/ — flat, one file per entity, kebab-case singular.
• packages/shared/src/contracts/ — callable input/output schemas, one file per domain.
• apps/website/src/components/ — PascalCase files at root for cross-cutting; kebab-case subfolders per domain (expense/, tax/, inbox/, portfolio/, ask/, ca/, auth/, onboarding/, payment/, settings/, ui/, app/ and so on).
• apps/mobile/src/ — mirrors website: services/, stores/, components/, app/ (Expo Router).
• No dumping grounds. No misc/, common/, helpers/, shared-utils/.

Symbols

Kind	Convention	Example
Function	camelCase, verb-first	computeRollup, dispatchInvite
React component	PascalCase	ExpenseReviewCard
React hook	useCamelCase	useTaxConcern
Boolean	is/has/can/should prefix	isPaid, hasConsent
Module-level constant	SCREAMING_SNAKE_CASE	MAX_UPLOAD_BYTES
Type / Interface / Zod export	PascalCase	ExpenseRollup
Zod schema variable	pascalCase + Schema suffix	expenseRollupSchema
Callable / event name	kebab-case verb-noun	submit-tax-concern
Firestore collection	kebab-case, plural	tax-concerns
Firestore field	camelCase	createdAt, assessmentYear

Forbidden: Hungarian prefixes (strName), data/info/obj as names, single-letter names outside tight loops, non-standard abbreviations (usr, cfg — write user, config).

Imports and exports

• React components: one per file, export default, file named after the component.
• Everything else (hooks, utils, schemas, constants, types): named exports.
• No barrel files in apps/website. Import the module directly — a barrel makes every page compile the whole folder and gives the codebase two ways to import one thing. index.ts re-exports stay allowed only in packages/shared and apps/functions/_lib, where they are the package's public surface.
• Import order: external → workspace packages → relative. No deep cross-domain relative imports (../../tax/foo) — go through the package boundary.