Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Shared Package Architecture

​

Purpose

• Frontend (src/) — the React web application
• Cloud Functions (functions/) — Firebase Cloud Functions (Node.js)

​

Workspace Setup

{
  "workspaces": ["packages/*", "functions"]
}

// functions/package.json
{
  "dependencies": {
    "@grantmaster/shared": "*"
  }
}

​

Package Structure

packages/shared/
├── package.json          # Package manifest with named exports
└── src/
    ├── index.ts          # Barrel re-export of all sub-modules
    ├── types/
    │   ├── index.ts
    │   ├── enums.ts      # Domain enums and constants
    │   ├── common.ts     # Base document interfaces
    │   ├── entities.ts   # Minimal entity shapes for Functions
    │   └── intelligence.ts # Cross-org analytics types
    ├── schemas/
    │   ├── index.ts
    │   └── common.schema.ts # Zod schemas for shared validation
    ├── errors/
    │   ├── index.ts
    │   ├── AppError.ts   # Error hierarchy base classes
    │   └── domain.ts     # Domain-specific error classes
    ├── events/
    │   └── index.ts      # SystemEventType enum and typed payloads
    └── config/
        ├── index.ts
        └── entitlements.ts # Feature flags and subscription limits

​

Named Exports (package.json)

{
  "exports": {
    ".":          "./src/index.ts",
    "./events":   "./src/events.ts",
    "./schemas":  "./src/schemas/index.ts",
    "./errors":   "./src/errors/index.ts",
    "./events":   "./src/events/index.ts",
    "./config":   "./src/config/index.ts"
  }
}

import { SystemRole } from '@grantmaster/shared';
import { SystemRole } from '@grantmaster/shared/types';

​

What Gets Shared

​

Types (@grantmaster/shared/types)

​

enums.ts — Domain Enumerations and Constants

​

common.ts — Base Document Interfaces

interface BaseDocument {
  id: string;
  organizationId: string;
  createdAt: TimestampLike;
  updatedAt: TimestampLike;
}

interface AuditedDocument extends BaseDocument {
  createdBy: string;
  createdByName: string;
  updatedBy: string;
  updatedByName: string;
}

​

entities.ts — Minimal Entity Shapes

• ProjectBase — id, organizationId, name, phase, budget
• EmployeeBase — id, organizationId, displayName, email, systemRole

​

intelligence.ts — Cross-Org Analytics

​

Schemas (@grantmaster/shared/schemas)

​

Errors (@grantmaster/shared/errors)

AppError (base)
├── UserError          # 4xx — caused by user input or state
│   ├── ValidationError
│   ├── AuthenticationError
│   ├── AuthorizationError
│   └── NotFoundError
└── SystemError        # 5xx — internal failures
    ├── FirestoreError
    ├── StorageError
    ├── NetworkError
    ├── RateLimitError
    ├── BusinessLogicError
    ├── ExternalAPIError
    ├── AIServiceError
    └── EmailServiceError

​

Events (@grantmaster/shared/events)

​

SystemEventType

​

SystemEvent<T> Interface

interface SystemEvent<T = unknown> {
  type: SystemEventType;
  organizationId: string;
  userId: string;
  severity: EventSeverity;
  timestamp: TimestampLike;
  payload: T;
  metadata?: Record<string, unknown>;
}

​

Type Guards

isJournalEvent(event: SystemEvent): event is SystemEvent<JournalEventPayload>
isExpenseEvent(event: SystemEvent): event is SystemEvent<ExpenseEventPayload>
// ... one per domain group

​

requiresPersistence(eventType)

​

Config (@grantmaster/shared/config)

​

Feature Enum

​

TierLimits and TIER_LIMITS

interface TierLimits {
  maxUsers: number;
  maxProjects: number;
  maxStorageGB: number;
  maxApiCallsPerMonth: number;
  maxAIGenerationsPerMonth: number;
  maxAgentCreditsPerMonth: number;
  maxAgentRunsPerMonth: number;
}

​

Helper Functions

​

How to Add New Shared Code

​

Decision checklist

• It is consumed by at least two of: frontend, Cloud Functions
• It contains no Firebase imports (no firebase/app, firebase/firestore, firebase-admin/*)
• It contains no browser APIs (window, document, localStorage)
• It contains no Node.js built-ins that are not available in both environments

​

Steps

1. Choose the right sub-module based on what you are adding:

   What you are adding	Sub-module
   A domain enum or constant	owning shared or feature contract module
   A base document interface	owning schema or shared contract module
   A minimal entity shape for Functions	owning shared contract module
   A Zod validation schema	src/schemas/common.schema.ts
   A new error class	src/errors/AppError.ts or src/errors/domain.ts
   A new event type	src/events/index.ts
   A feature flag or tier limit	src/config/entitlements.ts

2. Write the code in the chosen file. Follow the existing style — use export on all public symbols.
3. Re-export from the sub-module’s index.ts if the file has one.
4. Verify the root barrel (src/index.ts) re-exports the sub-module. It should already, since it re-exports ./types, ./schemas, ./errors, ./events, and ./config wholesale.
5. Run the TypeScript compiler across both consumers to catch any issues:
   # From repo root
   npm run build           # checks frontend
   npm run build --workspace=functions  # checks Cloud Functions
   
6. Do not add new runtime dependencies without team discussion. The package intentionally has only one runtime dependency (zod). Adding Firebase, Lodash, or similar libraries defeats the purpose of the package being environment-agnostic.

​

Adding a New Event Type

1. Add the new value to SystemEventType in src/events/index.ts.
2. Define a typed payload interface (e.g. MyDomainEventPayload).
3. Extend the relevant type guard or add a new one.
4. Update requiresPersistence() if the event must be written to Firestore.
5. In the consuming service, emit via EventBus.emit(SystemEventType.MY_EVENT, payload) following the EventBus rule in docs/engineering/architecture/base-service-and-eventbus.md.

​

Adding a New Error Class

1. Decide whether it is a UserError (client mistake) or SystemError (internal failure).
2. Extend the appropriate base class in src/errors/AppError.ts (for general errors) or src/errors/domain.ts (for platform-specific errors).
3. Set a meaningful severity and category in the constructor.
4. Export from src/errors/index.ts.

​

Dependency Rule Summary