Initial commit

.cursor/rules/01-global-engineering.mdc

@@ -0,0 +1,93 @@
+---
+description: Core engineering principles, TypeScript, validation, and definition of done
+alwaysApply: true
+---
+
+You are working in a TypeScript-first monorepo for a modern HOA management platform.
+
+## Project structure
+- This repository uses `pnpm` workspaces.
+- Top-level workspace structure:
+  - `apps/web` — Next.js frontend
+  - `apps/api` — Fastify backend
+  - `packages/*` — shared packages
+- Prefer shared packages from the start for reusable concerns such as UI primitives, types, config, i18n, lint config, and tsconfig.
+
+## Core engineering principles
+- Prefer maintainability, clarity, and explicitness over cleverness.
+- Prefer fewer dependencies unless a new dependency is clearly justified.
+- When adding a dependency, always use the latest stable non-beta version.
+- Do not add packages when platform features or existing dependencies are sufficient.
+- Do not introduce anti-patterns.
+- Always follow established patterns in the codebase.
+- If a requested change conflicts with established architecture or patterns, stop and ask before proceeding.
+
+## Planning and execution
+- Before making large changes, propose a brief implementation plan first.
+- “Large changes” include:
+  - modifications across multiple files
+  - schema changes
+  - new dependencies
+  - architecture changes
+  - changes spanning multiple workspaces
+- Prefer small, reviewable changes over sweeping rewrites unless explicitly instructed otherwise.
+
+## File and code organization
+- Prefer modifying existing files over creating new abstractions unless a new abstraction is justified.
+- Avoid speculative abstractions. Generalize after a second real use case.
+- Do not create multi-thousand-line files.
+- Split large files into focused modules before they become unwieldy.
+- Keep modules small and cohesive.
+- Prefer composition over inheritance.
+- Prefer pure functions where practical.
+- Do not create giant utility dumping-ground files.
+
+## TypeScript standards
+- Use strict TypeScript patterns.
+- Avoid `any` unless absolutely unavoidable and explicitly justified.
+- Prefer precise types, discriminated unions, and explicit return types where helpful for maintainability.
+- Shared types and schemas should live in dedicated packages when reused across workspaces.
+- **Always use extensionless imports.** Write `import { foo } from './foo'`, never `import { foo } from './foo.js'`. All TypeScript is processed by `tsx`, Next.js, or Vitest — none require explicit extensions. An ESLint rule enforces this.
+
+## Validation and safety
+- Validate all external boundaries.
+- This includes:
+  - API request validation
+  - API response validation where appropriate
+  - environment variable validation
+  - form validation
+  - file upload validation
+- Use Zod as the default schema validation library unless explicitly directed otherwise.
+- **Examples:** Validate request body and params at every API route boundary; validate environment variables at app startup (e.g. with a Zod schema) and fail fast if invalid.
+
+## Documentation
+- Add JSDoc for every non-trivial function or method, whether internal or exported.
+- JSDoc should be useful, not decorative.
+- Include parameter descriptions, return values, thrown errors where relevant, and examples when useful.
+- Do not add comments that merely restate obvious code.
+
+## Definition of done
+- Before considering work complete, run the smallest relevant checks during development and the full validation suite before finalizing.
+- Full validation includes:
+  - Prettier
+  - lint
+  - typecheck
+  - tests
+- Never mark work complete if lint, typecheck, or tests fail.
+- When finalizing, summarize what checks were run and their outcome.
+
+## Documentation and repo hygiene
+- Keep related documentation up to date when behavior changes.
+- This includes, where relevant:
+  - README files
+  - environment examples
+  - package scripts
+  - API docs
+  - setup docs
+- New apps or packages should include appropriate scripts, test setup, lint/typecheck setup, and a README.
+
+## Security and secrets
+- Never hard-code secrets.
+- Never commit mock credentials or insecure defaults.
+- Secrets must only be stored in environment variables or the database, whichever is appropriate for the use case.
+- Prefer secure defaults.

.cursor/rules/02-monorepo-and-dependencies.mdc

@@ -0,0 +1,29 @@
+---
+description: pnpm workspaces, dependency rules, and shared package direction
+alwaysApply: true
+---
+
+Shared package and dependency standards for the monorepo.
+
+## Package management
+- Use `pnpm` workspaces.
+- Prefer workspace packages for shared logic rather than duplication between apps.
+- Reusable logic should be extracted into `packages/*` only when there is a clear second use case or a foundational shared concern.
+
+## Dependency rules
+- Prefer fewer dependencies.
+- Do not introduce a package solely for convenience if existing platform APIs or current project dependencies can solve the problem cleanly.
+- Any new dependency must be justified briefly in code comments, PR notes, or task summary when it is not obvious.
+- Use the latest stable non-beta version when adding dependencies.
+- Prefer mature, actively maintained packages with strong TypeScript support.
+
+## Shared package direction
+Prefer dedicated packages for:
+- UI primitives
+- shared types
+- shared schemas
+- configuration
+- internationalization helpers
+- eslint config
+- tsconfig
+- test utilities when broadly reused

.cursor/rules/03-backend-api.mdc

@@ -0,0 +1,83 @@
+---
+description: Fastify backend, API design, Prisma, auth, and error handling
+globs: apps/api/**/*
+alwaysApply: false
+---
+
+You are working on the backend in `apps/api`.
+
+## Backend framework
+- Use Fastify as the default backend framework.
+- Prefer Fastify plugins and encapsulation patterns over ad hoc global behavior.
+
+## API design
+- Keep business logic out of route handlers.
+- Route handlers should be thin and focused on:
+  - validation
+  - auth/context
+  - calling application services
+  - shaping responses
+- Prefer explicit service-layer or domain-layer boundaries for business logic.
+
+## Validation and contracts
+- Validate all incoming requests with Zod or approved schema wrappers.
+- Validate file uploads and all user-controlled input.
+- Avoid trusting frontend input.
+- Use explicit schemas for request and response shapes where practical.
+
+## API documentation
+- Maintain Swagger/OpenAPI support.
+- New or changed endpoints should update the API schema/docs as part of the work.
+- Keep API docs accurate and usable.
+
+## Data access
+- Prefer Prisma as the default ORM unless explicitly directed otherwise.
+- Use Postgres as the primary relational database.
+- Store relational/domain data in Postgres.
+- Store document/image metadata in Postgres and file binaries in appropriate storage.
+- Avoid leaking raw ORM/database logic into unrelated layers.
+
+## Auth and permissions
+- Roles and permissions are first-class concerns.
+- Design with support for:
+  - board members
+  - treasurers
+  - owners
+  - tenants
+  - future administrative roles
+- Support passwordless authentication patterns:
+  - magic link
+  - OIDC
+  - passkeys
+- Do not hard-code assumptions that one deployment always maps to one HOA.
+- Self-hosted mode supports single tenancy.
+- SaaS mode must remain compatible with future or current multi-tenant architecture decisions.
+
+## Auditing
+- All destructive or sensitive actions must be auditable.
+- Deletions and other important changes should be recorded in an audit log.
+- Prefer soft-delete or explicit audit-aware flows where appropriate.
+- Do not implement silent destructive behavior.
+
+## Error handling
+- Use explicit, typed, and user-safe error handling.
+- Never use silent catch blocks.
+- Do not swallow errors.
+- Return structured, predictable error responses.
+
+**Example:**
+
+```typescript
+// BAD: silent catch
+try {
+  await doSomething();
+} catch {}
+
+// GOOD: log, type, rethrow or return structured error
+try {
+  await doSomething();
+} catch (e) {
+  logger.error({ err: e }, 'doSomething failed');
+  throw new ServiceError('Operation failed', { cause: e });
+}
+```

.cursor/rules/04-frontend-web.mdc

@@ -0,0 +1,62 @@
+---
+description: Next.js frontend, UI structure, CSS Modules, a11y, Storybook
+globs: apps/web/**/*
+alwaysApply: false
+---
+
+You are working on the frontend in `apps/web`.
+
+## Framework and rendering
+- Use Next.js.
+- Prefer Server Components where appropriate.
+- Avoid unnecessary client components.
+- Keep data-fetching and business logic out of presentational layers.
+
+## UI structure
+Use the following frontend structure consistently:
+- `components` = pure presentational building blocks and small UI pieces
+- `widgets` = composed UI units with local behavior
+- `views` = page-level compositions of components and widgets
+
+## Component behavior
+- Components may include local UI behavior where appropriate, such as disclosure, accordion, or local interaction state.
+- Components must not make API calls or contain unrelated side effects on their own.
+- Heavy business logic must not live in the UI presentation layer.
+- Data shaping and domain logic should live outside presentational components.
+
+## Shared UI
+- Shared UI primitives belong in a dedicated UI package.
+- Do not duplicate shared primitives inside app-specific code.
+- App-level components may compose primitives from the UI package.
+
+## Styling
+- Tailwind is forbidden.
+- Use CSS Modules for component styling.
+- Use PostCSS for CSS processing.
+- Use design tokens and CSS custom properties first.
+- Avoid ad hoc spacing, color, and sizing values.
+- Prefer token-based styling.
+- Use inline styles only when truly necessary for dynamic one-off values.
+- Stylelint should be part of linting and style validation.
+- Target modern browsers only.
+- Use modern CSS features appropriate for current browser support, including CSS nesting / modern syntax supported by the project PostCSS setup.
+
+## Accessibility
+Accessibility is a primary requirement.
+- Prefer semantic HTML first.
+- All interactive UI must be keyboard operable.
+- Always provide visible focus states.
+- Use proper labels and accessible names.
+- Maintain color contrast awareness.
+- Use ARIA only when native semantics are insufficient.
+- Consider accessibility during implementation, not as an afterthought.
+
+## Storybook
+- Every component and widget should have Storybook stories.
+- Stories should include:
+  - default states
+  - loading states where relevant
+  - empty/error states where relevant
+  - accessibility-relevant and keyboard-relevant states where useful
+- Include controls and docs in stories.
+- Follow i18n patterns in stories where applicable.

.cursor/rules/05-i18n.mdc

@@ -0,0 +1,18 @@
+---
+description: Frontend i18n with next-intl, localization, and translation file layout
+globs: apps/web/**/*
+alwaysApply: false
+---
+
+Frontend internationalization with next-intl and localized copy.
+
+## Internationalization
+- Build with `next-intl` from the beginning.
+- All user-facing strings must be localized.
+- Do not hard-code user-facing copy directly in UI components.
+- Use component-local translation files where appropriate.
+- Translation files should live alongside components using `translations.json` where applicable.
+- Use `common.json` only for truly shared/common strings.
+- Keep translation keys organized, scoped, and maintainable.
+- Do not dump unrelated strings into generic namespaces.
+- Storybook examples and component examples should follow i18n conventions where relevant.

.cursor/rules/06-testing.mdc

@@ -0,0 +1,42 @@
+---
+description: Testing philosophy, Vitest/Playwright, coverage, and mocking
+alwaysApply: true
+---
+
+Testing standards and tooling for the project.
+
+## Testing philosophy
+- Every meaningful code change should include appropriate test coverage.
+- New files, functions, and methods should receive comprehensive test coverage where relevant.
+- Definition of done includes tests passing.
+
+## Required test layers
+Use the appropriate mix of:
+- unit tests
+- integration tests
+- component tests
+- e2e tests where relevant
+
+## Tooling defaults
+- Use Vitest for unit and integration testing unless explicitly directed otherwise.
+- Use Playwright for end-to-end testing.
+- Use Testing Library patterns for UI/component tests where appropriate.
+
+## Coverage expectations
+- Maintain a minimum of 85% coverage per app/package.
+- Coverage should include:
+  - happy paths
+  - edge cases
+  - error cases
+
+## Mocking standards
+- Do not create duplicate mocks.
+- Prefer centralized, reusable mocks, fixtures, and test factories.
+- Integration tests should prefer realistic boundaries and minimal mocking.
+- Unit tests may use mocks where appropriate, but shared mocks should be reused rather than redefined ad hoc.
+
+## Quality standards
+- Tests should be readable, deterministic, and isolated.
+- Avoid brittle tests coupled to implementation details.
+- Temporary test omissions are allowed only when explicitly acknowledged, but the work is not complete until the full test expectation is satisfied.
+- Where practical, include accessibility-oriented testing for components and flows.

.cursor/rules/07-auth-permissions-audit.mdc

@@ -0,0 +1,29 @@
+---
+description: Identity, authorization, and auditability
+alwaysApply: true
+---
+
+Auth, permissions, and audit requirements.
+
+## Identity and access
+- Authentication is passwordless-first.
+- Prefer support for:
+  - magic links
+  - OIDC
+  - passkeys
+- Roles and permissions are core architecture concerns and must not be deferred casually.
+
+## Authorization
+- Never assume all authenticated users have broad access.
+- Design authorization around role-aware and context-aware access rules.
+- Support evolving permission models without hard-coding simplistic assumptions.
+
+## Auditability
+- Important actions must be auditable.
+- This includes at minimum:
+  - deletions
+  - updates to sensitive records
+  - role/permission changes
+  - financial changes
+  - document-related changes where relevant
+- Preserve historical traceability wherever practical.

.cursor/rules/08-agent-behavior.mdc

@@ -0,0 +1,23 @@
+---
+description: When to ask before acting and change strategy
+alwaysApply: true
+---
+
+When to ask the user and how to scope changes.
+
+## Ask before proceeding when:
+- deleting files
+- changing public interfaces
+- making destructive schema changes
+- adding new dependencies
+- changing established architecture
+- introducing patterns inconsistent with the existing codebase
+
+Unless the action was explicitly requested as part of the approved plan, stop and ask first.
+
+## Change strategy
+- Prefer incremental, reversible changes.
+- Do not perform broad unrelated refactors while addressing a focused request unless explicitly asked.
+- Keep implementation scoped to the task.
+
+**Example:** User asked to fix a bug in component X — do not refactor unrelated components or add a new dependency unless the fix requires it. User asked to add feature Y that needs a new dependency — if that was not in an approved plan, ask before adding the dependency.