Imported from Stringsaeed/BrimApp (AGENTS.md). Install upstream with npx skills add Stringsaeed/BrimApp. Copyright stays with the author.

BrimApp Agent Guide

Project Snapshot

• App type: Expo + React Native note-taking app with web support
• Router: Expo Router (src/app)
• UI system: Tamagui (src/themes/theme.ts)
• Data sync: Supabase + Legend-State (src/services/database)
• Forms: Formik + Zod
• Error reporting: Sentry (src/services/sentry)
• Feature flags: Flagsmith (src/services/flagsmith)
• Analytics: Vexo (src/services/vexo)
• Package manager: pnpm 10 (.npmrc)

Working Principles

• Prefer editing files under src/ unless the task explicitly requires native changes.
• Keep route wrappers in src/app thin and place UI/business logic in src/screens, src/components, src/hooks, and src/services.
• Use Tamagui components/tokens for UI primitives and theme values.
• Use the @/* path alias (maps to src/*) over deep relative imports.
• Report operational errors via Sentry (Sentry.captureException(...)) in async/mutation flows.

Repository Structure

• src/app: Expo Router entrypoints and route layout files.
• src/screens: Screen implementations (feature-oriented).
• src/components: Reusable UI building blocks, typically one folder per component with index.tsx.
• src/hooks: Custom hooks, grouped as use-<feature>/index.ts[x].
• src/contexts: React providers for auth, notes, query client, and feature-specific state.
• src/services: External and platform integrations (Supabase, Sentry, analytics, flags, storage, AI, toolbar).
• src/themes: Tamagui theme/font/animation configuration.
• src/types: Shared domain and integration types (including generated Supabase types).
• src/utils: Pure helpers and shared test utilities.
• supabase: Local Supabase config and SQL migrations.
• assets: App icons/splash/art assets.
• ios, android: Native projects for prebuild/ejected workflows.
• .github/workflows: CI workflows (codeql.yml, update.yml).

Routing and Screen Conventions

• Route definitions live in src/app, but route files usually only re-export screens from src/screens.
• Route groups are used:
• (app) for authenticated/main app routes
• auth for auth modal stack
• Global provider and stack setup is centralized in src/app/_layout.tsx.
• Canonical route constants live in src/routers/index.ts (Routes enum). Use these instead of hardcoded paths.

State, Data, and Services

• Notes sync:
• notes$ observable is configured in src/services/database/index.ts.
• Supabase sync uses realtime + soft delete (deleted_at) + async persistence.
• NoteService (src/services/notes/notes.ts) is the primary CRUD surface for note operations.
• Auth:
• AuthenticationProvider in src/contexts/auth/index.tsx wraps Supabase auth state.
• Query/mutations:
• React Query client is created in src/contexts/query/index.tsx.
• Feature hooks under src/hooks/use-*-mutation should own async side effects and error capture.
• Storage:
• src/services/storage/index.ts wraps MMKV with async-like methods.

Environment and Config

• Runtime env is validated with Zod in src/config/env/index.ts.
• Required public env keys:
• EXPO_PUBLIC_FLAGSMITH_ENVIRONMENT_ID
• EXPO_PUBLIC_VEXO_ANALYTICS_API_KEY
• EXPO_PUBLIC_SUPABASE_ANON_KEY
• EXPO_PUBLIC_GEMINI_API_KEY
• EXPO_PUBLIC_SUPABASE_URL
• EXPO_PUBLIC_SENTRY_DSN
• Build/release env keys also used:
• SENTRY_AUTH_TOKEN
• SENTRY_PROJECT
• SENTRY_ORG
• App variants are configured in app.config.ts using APP_VARIANT (development, preview, production).

Coding Standards

• Language: TypeScript (strict mode on).
• Formatting/Linting: Biome (2-space indentation, double quotes, semicolons, trailing commas es5).
• Imports:
• Enforce group order: builtin -> external -> internal -> parent -> sibling -> index.
• Alphabetize ascending with blank lines between groups.
• Lint highlights:
• no-console is error.
• Keep one blank line after imports.
• UI:
• Prefer Tamagui components and tokens ($background, $color, $<accent>).
• Use React Native primitives directly only when needed for platform APIs/layout edge cases.
• Types/validation:
• Prefer explicit interfaces/types.
• Use Zod for schema validation and parsing (src/types, src/utils/validation.ts, src/config/env).

Testing Standards

• Framework: Jest with jest-expo.
• Test files: *.test.ts and *.test.tsx.
• Component tests should be colocated in __tests__ directories where practical.
• Prefer src/utils/test.tsx custom render helper for provider-wrapped component tests.
• Snapshot testing is used and acceptable for stable UI structures.
• Coverage is collected from src/**/*.{ts,tsx}.

Commands

• pnpm start: Start Expo dev server.
• pnpm start:web: Start web build (TAMAGUI_TARGET=web).
• pnpm start:clear: Start with cleared cache.
• pnpm ios: Run iOS app.
• pnpm android: Run Android app.
• pnpm lint: Run Biome lint check.
• pnpm lint:write: Run Biome lint with auto-fixes.
• pnpm format: Run Biome formatter check.
• pnpm format:write: Run Biome formatter with auto-write.
• pnpm lint_format:check: Run Biome lint+format check.
• pnpm lint_format:check:write: Run Biome lint+format check with auto-write.
• pnpm check: TypeScript check (tsc --noEmit).
• pnpm validate: format + lint.
• pnpm validate:strict: validate + check.
• pnpm test: Run all tests.
• pnpm test -- path/to/file.test.tsx: Run a specific test file.
• pnpm checkDead: Dead code and unused export scan via Knip.
• pnpm supabase:start|stop|status|studio: Local Supabase lifecycle.
• pnpm supabase:db:push|pull|reset: Schema management.
• pnpm supabase:gen:types: Regenerate src/types/supabase.ts.

Git and CI Workflow

• Git hooks are managed with Lefthook.
• Pre-commit currently runs:
• pnpm lint
• pnpm exec biome check --write {staged_files}
• Commit message hook runs commitlint (@commitlint/config-conventional).
• Allowed commit types:
• build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
• CI:
• .github/workflows/update.yml runs on push and executes pnpm validate:strict before eas update --auto.
• .github/workflows/codeql.yml performs security analysis on main and on schedule.

Supabase Notes

• Current base migration creates notes table with:
• id, title, note, status, is_private, user_id, created_at, updated_at, deleted_at.
• Realtime is enabled for notes.
• Trigger handle_times maintains created_at and updated_at.

Agent Checklist Before Handoff

• Run pnpm validate:strict for production-facing changes.
• Run relevant tests (pnpm test or targeted test files) when behavior changes.
• Regenerate Supabase types when schema changes.
• Keep route wrappers thin and avoid business logic in src/app files.
• Confirm no secrets are committed from .env or service credential files.