@digimuza/saas-core 0.0.2

package/CLAUDE.md

@@ -0,0 +1,1165 @@
+# @digimuza/saas-core
+
+## Purpose
+
+@digimuza/saas-core is a reusable SaaS foundation for building multiple SaaS applications.
+
+The goal is to eliminate repeatedly rebuilding SaaS infrastructure while keeping product-specific business logic outside the core.
+
+The package must provide a simple, strongly typed foundation for:
+
+- Authentication
+- Users and profiles
+- Workspaces / multi-tenancy
+- Workspace memberships
+- Customizable roles
+- Multiple roles per user
+- Permissions
+- Environment configuration
+- Runtime configuration
+- Billing
+- Entitlements
+- Background jobs
+- Durable workflows
+- Application events
+- Realtime communication
+- RxJS-based reactive behaviors
+- Email
+- Notifications
+- Audit logs
+- API keys
+- Webhooks
+- Feature flags
+- Storage
+
+The primary design principle is:
+
+"Use the simplest infrastructure that reliably solves the problem."
+
+---
+
+# Technology
+
+Use:
+
+- TypeScript
+- Next.js
+- PostgreSQL
+- Drizzle ORM
+- Zod
+- RxJS
+- Vitest
+- Playwright when UI testing is required
+
+External services:
+
+- WorkOS -> authentication and identity
+- Infisical -> environment configuration and secrets
+- Revolut -> billing/payments
+- Trigger.dev -> durable background execution
+- Open-source realtime infrastructure -> realtime transport when required
+
+Do not introduce additional infrastructure without a concrete requirement.
+
+---
+
+# Core Philosophy
+
+## Simplicity
+
+Prefer:
+
+PostgreSQL over Redis when PostgreSQL is sufficient.
+
+Next.js over a separate backend when Next.js is sufficient.
+
+Managed infrastructure over infrastructure that must be manually operated.
+
+Explicit APIs over magic.
+
+Small abstractions over generic frameworks.
+
+Do not introduce microservices.
+
+Do not build custom infrastructure when a mature service already solves the problem.
+
+Do not optimize for hypothetical scale.
+
+Optimize for:
+
+- simplicity
+- maintainability
+- security
+- developer experience
+- reliability
+
+---
+
+# Package
+
+Everything belongs to ONE npm package:
+
+@digimuza/saas-core
+
+Use subpath exports:
+
+@digimuza/saas-core/auth
+@digimuza/saas-core/db
+@digimuza/saas-core/users
+@digimuza/saas-core/workspaces
+@digimuza/saas-core/authorization
+@digimuza/saas-core/config
+@digimuza/saas-core/billing
+@digimuza/saas-core/entitlements
+@digimuza/saas-core/jobs
+@digimuza/saas-core/events
+@digimuza/saas-core/realtime
+@digimuza/saas-core/email
+@digimuza/saas-core/notifications
+@digimuza/saas-core/audit
+@digimuza/saas-core/api-keys
+@digimuza/saas-core/webhooks
+@digimuza/saas-core/feature-flags
+@digimuza/saas-core/storage
+
+Do NOT create separate npm packages.
+
+---
+
+# Database
+
+Use PostgreSQL + Drizzle ORM.
+
+Do NOT use Prisma.
+
+Database schema definitions are part of the public package.
+
+Export them from:
+
+@digimuza/saas-core/db/schema
+
+Applications must be able to import core tables and reference them from product-specific tables.
+
+Example:
+
+import { workspaces } from "@digimuza/saas-core/db/schema";
+
+export const projects = pgTable("projects", {
+  id: uuid("id").defaultRandom().primaryKey(),
+
+  workspaceId: uuid("workspace_id")
+    .notNull()
+    .references(() => workspaces.id),
+
+  name: text("name").notNull(),
+});
+
+The core owns platform tables.
+
+Individual SaaS applications own product-specific tables.
+
+---
+
+# Database Ownership
+
+Core-owned tables include:
+
+users
+user_profiles
+workspaces
+workspace_members
+roles
+permissions
+workspace_member_roles
+role_permissions
+plans
+billing_customers
+subscriptions
+billing_events
+entitlements
+audit_logs
+notifications
+api_keys
+webhooks
+feature_flags
+events
+usage_records where appropriate
+
+Product applications own:
+
+projects
+documents
+messages
+AI-specific entities
+product-specific configuration
+product-specific business logic
+
+Never put product-specific domain models into the core unless they clearly apply to multiple SaaS products.
+
+---
+
+# Users
+
+Separate authentication identity from user profile.
+
+users:
+
+- id
+- workos_user_id
+- created_at
+- updated_at
+
+user_profiles:
+
+- user_id
+- email
+- first_name
+- last_name
+- display_name
+- avatar_url
+- created_at
+- updated_at
+
+Email belongs to user_profiles.
+
+Do not duplicate email in users.
+
+Do not store passwords.
+
+---
+
+# Authentication
+
+Use WorkOS.
+
+Do not implement OAuth, SAML or OIDC manually.
+
+Application code should use:
+
+auth.getCurrentUser()
+auth.requireUser()
+auth.getSession()
+auth.signOut()
+
+Do not expose WorkOS implementation details throughout application code.
+
+Support WorkOS capabilities where applicable:
+
+- Google/social login
+- Email authentication
+- Passkeys
+- MFA
+- SAML
+- OIDC
+- Account linking
+- Sessions
+
+---
+
+# Workspaces
+
+Users can belong to multiple workspaces.
+
+Never put workspace_id on users.
+
+Use:
+
+users
+  -> workspace_members
+  -> workspaces
+
+A workspace membership represents the user's relationship with a workspace.
+
+Expose:
+
+workspaces.create()
+workspaces.get()
+workspaces.update()
+workspaces.delete()
+workspaces.getCurrent()
+workspaces.members.list()
+workspaces.members.invite()
+workspaces.members.remove()
+
+All tenant-sensitive operations must verify workspace membership.
+
+Never trust workspace_id supplied by a client.
+
+---
+
+# Roles
+
+Roles are workspace-scoped.
+
+roles:
+
+- id
+- workspace_id
+- name
+- description
+- created_at
+- updated_at
+
+Users may have multiple roles.
+
+workspace_member_roles:
+
+- workspace_id
+- user_id
+- role_id
+
+PostgreSQL constraints must prevent cross-workspace role assignments.
+
+Support:
+
+- system roles
+- default roles
+- custom roles
+
+Do not hard-code role names into authorization logic.
+
+---
+
+# Permissions
+
+Permissions are application-defined.
+
+Examples:
+
+workspace.read
+workspace.update
+members.read
+members.invite
+members.remove
+projects.read
+projects.create
+projects.update
+projects.delete
+billing.read
+billing.update
+
+Roles receive permissions through:
+
+role_permissions
+
+Effective permissions are the UNION of permissions from all roles assigned to the user within the workspace.
+
+Expose:
+
+authorization.can()
+authorization.require()
+authorization.hasRole()
+
+Authorization always requires workspace context.
+
+---
+
+# Configuration
+
+Do NOT use .env files as the project's configuration management strategy.
+
+Use Infisical.
+
+Infisical is responsible for injecting secrets and environment configuration into the application runtime.
+
+The core must not depend directly on the Infisical API during normal application execution.
+
+Only the configuration module may access process.env.
+
+Application code must never access process.env directly.
+
+Provide typed configuration:
+
+config.app
+config.database
+config.auth
+config.billing
+config.email
+config.storage
+config.realtime
+config.jobs
+
+Configuration must:
+
+- be strongly typed
+- be validated with Zod
+- fail fast
+- separate server and client configuration
+- prevent server secrets from entering client bundles
+
+Infrastructure secrets must never be stored in PostgreSQL.
+
+Runtime application configuration may be stored in PostgreSQL.
+
+Examples:
+
+- workspace timezone
+- locale
+- branding
+- workspace settings
+- product configuration
+
+---
+
+# Billing
+
+Use Revolut initially.
+
+Do not expose Revolut-specific APIs throughout the application.
+
+Expose:
+
+billing.getCustomer()
+billing.createCheckout()
+billing.getSubscription()
+billing.cancelSubscription()
+billing.getPortal()
+
+Database entities:
+
+plans
+billing_customers
+subscriptions
+billing_events
+
+Billing state is updated from verified webhook events.
+
+Keep the billing abstraction provider-independent enough to support another provider later.
+
+Do not implement payment processing.
+
+---
+
+# Entitlements
+
+Billing and authorization are separate.
+
+Model:
+
+Subscription
+  -> Plan
+  -> Entitlements
+  -> Features and limits
+
+Examples:
+
+advanced_analytics
+ai_generation
+api_access
+custom_domains
+
+Limits:
+
+ai_generations
+team_members
+storage_bytes
+api_requests
+
+Expose:
+
+entitlements.has()
+entitlements.require()
+entitlements.getLimit()
+entitlements.checkLimit()
+
+Product code must not inspect subscription plan names directly.
+
+Use entitlements.
+
+---
+
+# Background Jobs
+
+Use Trigger.dev for durable execution.
+
+Do not implement a custom durable execution engine.
+
+Use Trigger.dev for:
+
+- long-running jobs
+- retries
+- scheduling
+- cron
+- durable workflows
+- multi-step workflows
+- waits
+- concurrency
+- task observability
+
+Expose a thin integration:
+
+jobs.trigger()
+
+Do not unnecessarily hide Trigger.dev functionality.
+
+The core should allow advanced applications to access Trigger.dev capabilities when required.
+
+Do not introduce Redis solely for background jobs.
+
+---
+
+# Events
+
+Create a unified application event model.
+
+An event represents something that happened in the application.
+
+Example:
+
+events.publish({
+  type: "project.created",
+  workspaceId,
+  actorId,
+  data: {
+    projectId
+  }
+})
+
+Events must contain:
+
+- id
+- type
+- timestamp
+- workspace context when applicable
+- actor context when applicable
+- typed payload
+
+Events may feed:
+
+- realtime
+- RxJS streams
+- notifications
+- audit logs
+- webhooks
+- Trigger.dev tasks
+
+Events should be strongly typed.
+
+Avoid a generic "anything JSON" event API when a typed event registry can be used.
+
+---
+
+# Realtime
+
+Realtime is responsible for delivering events to connected clients.
+
+It is NOT the durable source of truth.
+
+The architecture is:
+
+PostgreSQL
+  -> Application events
+  -> Realtime transport
+  -> Browser
+
+The realtime layer must support:
+
+- channels
+- workspace-scoped channels
+- user-scoped channels
+- authentication
+- authorization
+- reconnect
+- event delivery
+
+Clients must never be able to subscribe to unauthorized workspace channels.
+
+Do not expose PostgreSQL LISTEN/NOTIFY directly to browsers.
+
+PostgreSQL may be used internally as part of the event pipeline.
+
+The realtime implementation should be replaceable.
+
+---
+
+# RxJS Reactive Behavior Layer
+
+RxJS is a first-class dependency.
+
+RxJS is used for application-level reactive behavior.
+
+It is NOT the database.
+
+It is NOT the durable job system.
+
+It is NOT the realtime transport.
+
+Its responsibility is to:
+
+- consume realtime events
+- combine event streams
+- filter events
+- transform events
+- debounce events
+- throttle events
+- aggregate events
+- maintain reactive state
+- coordinate reactive behavior
+
+The conceptual architecture is:
+
+Event sources
+  -> Realtime / application events
+  -> RxJS Observable
+  -> Reactor
+  -> Application / client
+
+Expose a typed stream API.
+
+Example:
+
+const events$ = events.stream({
+  workspaceId
+});
+
+events$ returns:
+
+Observable<SaaSEvent>
+
+Example:
+
+const projectUpdates$ = events$
+  .pipe(
+    filter(event => event.type === "project.updated"),
+    map(event => event.data),
+    distinctUntilChanged()
+  );
+
+---
+
+# RxJS Rules
+
+Do not expose RxJS unnecessarily.
+
+Use Observable where streaming/reactive behavior provides clear value.
+
+Do not convert every synchronous API into an Observable.
+
+Prefer:
+
+Promise -> one-time asynchronous operation.
+
+Observable -> stream of values/events.
+
+Do not use RxJS for database access merely because RxJS exists.
+
+Do not use RxJS as a replacement for Trigger.dev.
+
+Do not use RxJS as a replacement for PostgreSQL persistence.
+
+Do not create infinite subscriptions without lifecycle management.
+
+Every subscription must have a clear lifecycle.
+
+Prefer operators such as:
+
+- map
+- filter
+- merge
+- switchMap
+- concatMap
+- exhaustMap
+- debounceTime
+- throttleTime
+- distinctUntilChanged
+- scan
+- share
+- shareReplay
+- takeUntil
+
+Use operators intentionally.
+
+Avoid deeply nested RxJS pipelines that become difficult to understand.
+
+---
+
+# Realtime + RxJS
+
+Realtime transport should feed RxJS.
+
+Example:
+
+realtime.subscribe(...)
+  -> Observable<SaaSEvent>
+  -> RxJS operators
+  -> Application behavior
+
+Do not make every UI component independently implement WebSocket behavior.
+
+Prefer a shared event abstraction.
+
+Example:
+
+const workspaceEvents$ =
+  realtime.events.workspace(workspaceId);
+
+Then:
+
+workspaceEvents$
+  .pipe(
+    filter(event => event.type === "notification.created")
+  )
+  .subscribe(...)
+
+The transport should be replaceable without changing the RxJS application API.
+
+---
+
+# Trigger.dev + RxJS
+
+Trigger.dev owns durable execution.
+
+RxJS owns reactive observation and behavior.
+
+Example:
+
+Trigger.dev task
+  -> job progress event
+  -> application event
+  -> realtime
+  -> RxJS Observable
+  -> browser UI
+
+Do not attempt to make RxJS durable.
+
+Do not keep state only in an Observable.
+
+If state must survive process restart, persist it in PostgreSQL.
+
+---
+
+# Realtime Event Examples
+
+Support patterns such as:
+
+job.started
+job.progress
+job.completed
+job.failed
+
+project.created
+project.updated
+project.deleted
+
+notification.created
+
+workspace.member.created
+workspace.member.removed
+workspace.member.role.updated
+
+billing.subscription.updated
+
+The event registry should provide compile-time type safety.
+
+---
+
+# Email
+
+Provide:
+
+email.send()
+email.sendTemplate()
+
+Keep provider-specific implementation behind an adapter.
+
+Templates may include:
+
+- welcome
+- invitation
+- security
+- billing
+- notifications
+
+---
+
+# Notifications
+
+Provide:
+
+notifications.create()
+notifications.list()
+notifications.markRead()
+
+Support:
+
+- in-app notifications
+- email notifications
+
+Notifications may consume application events.
+
+---
+
+# Audit
+
+Audit logs are durable and immutable.
+
+Example:
+
+audit.log({
+  action: "member.role.updated",
+  actorId,
+  workspaceId,
+  targetId,
+  metadata
+})
+
+Audit records include:
+
+- actor
+- workspace
+- action
+- target
+- metadata
+- timestamp
+- request ID where available
+
+Audit data must not be dependent on realtime delivery.
+
+If an audit event is important, it must be persisted.
+
+---
+
+# API Keys
+
+Workspace-scoped API keys.
+
+Requirements:
+
+- secure random generation
+- hash secrets
+- reveal secret only once
+- revoke
+- expiration
+- scopes
+- last-used timestamp
+
+Expose:
+
+apiKeys.create()
+apiKeys.revoke()
+apiKeys.validate()
+
+API key validation must resolve the workspace securely.
+
+---
+
+# Webhooks
+
+Support:
+
+- incoming webhooks
+- outgoing webhooks
+
+Outgoing webhook infrastructure should support:
+
+- endpoints
+- secrets
+- event subscriptions
+- delivery records
+- retries
+- failures
+
+Incoming webhooks must support:
+
+- signature verification
+- idempotency
+- event IDs
+- processing status
+
+---
+
+# Feature Flags
+
+Provide simple feature flags.
+
+Scopes:
+
+- global
+- application
+- workspace
+- user
+
+Expose:
+
+features.isEnabled()
+features.getVariant()
+
+Do not implement a complete feature management platform.
+
+---
+
+# Storage
+
+Provide:
+
+storage.upload()
+storage.delete()
+storage.getUrl()
+
+Use adapters.
+
+Do not couple product code to a specific storage provider.
+
+---
+
+# Security
+
+Security is a first-class requirement.
+
+Always enforce:
+
+- tenant isolation
+- authorization
+- input validation
+- API key security
+- webhook signatures
+- secret isolation
+- session security
+- realtime channel authorization
+- idempotency
+- auditability
+
+Never trust client-provided:
+
+userId
+workspaceId
+roleId
+permission information
+
+Resolve identity from authenticated context.
+
+---
+
+# Next.js
+
+First-class Next.js support.
+
+Support:
+
+- App Router
+- Server Components
+- Server Actions
+- Route Handlers
+- Middleware where appropriate
+
+Server-only modules must not be imported into client components.
+
+Never expose server secrets to the client.
+
+Prefer server-side operations.
+
+---
+
+# Testing
+
+Use Vitest for unit and integration tests.
+
+Use Playwright for end-to-end browser tests.
+
+Test:
+
+- workspace isolation
+- role assignment
+- multiple roles
+- permission resolution
+- authorization
+- billing webhook idempotency
+- API key validation
+- realtime authorization
+- event typing
+- RxJS stream behavior
+- RxJS subscription cleanup
+- reconnect behavior
+- Trigger.dev integration
+- entitlement checks
+
+Realtime tests must verify that users cannot receive events from unauthorized workspaces.
+
+RxJS tests should verify:
+
+- filtering
+- transformation
+- aggregation
+- debouncing/throttling
+- completion
+- error behavior
+- subscription cleanup
+
+---
+
+# Database Migration
+
+Use Drizzle migrations.
+
+Core schema definitions are exported publicly.
+
+Product applications may reference core tables.
+
+Core migrations must be versioned.
+
+Never modify production schemas manually.
+
+Destructive changes require a migration strategy.
+
+---
+
+# Dependency Rules
+
+Do not add a dependency unless:
+
+1. It solves a real problem.
+2. The problem cannot be solved simply with existing infrastructure.
+3. The dependency is actively maintained.
+4. The operational complexity is justified.
+
+Current infrastructure:
+
+PostgreSQL -> durable state
+
+Drizzle -> database access/schema
+
+WorkOS -> authentication
+
+Infisical -> secrets/configuration
+
+Revolut -> payments
+
+Trigger.dev -> durable execution
+
+RxJS -> reactive behavior
+
+Realtime transport -> event delivery
+
+Next.js -> application runtime
+
+Do not add Redis by default.
+
+---
+
+# Implementation Strategy
+
+Implement incrementally.
+
+For every feature:
+
+1. Define the problem.
+2. Determine whether it belongs in the core.
+3. Define the public API.
+4. Define the database schema.
+5. Define security boundaries.
+6. Define failure modes.
+7. Write tests.
+8. Implement the smallest useful solution.
+9. Document the API.
+
+Do not implement future features speculatively.
+
+---
+
+# Recommended Implementation Order
+
+Phase 1:
+- Drizzle
+- PostgreSQL
+- schema architecture
+- migrations
+- configuration
+- package exports
+
+Phase 2:
+- WorkOS
+- users
+- profiles
+
+Phase 3:
+- workspaces
+- memberships
+- invitations
+
+Phase 4:
+- roles
+- permissions
+- authorization
+
+Phase 5:
+- billing
+- plans
+- subscriptions
+- entitlements
+
+Phase 6:
+- application events
+- typed event registry
+
+Phase 7:
+- Trigger.dev
+- durable jobs
+- scheduled jobs
+
+Phase 8:
+- realtime transport
+- authenticated channels
+
+Phase 9:
+- RxJS reactive event streams
+- client subscriptions
+- event composition
+
+Phase 10:
+- email
+- notifications
+- audit logs
+
+Phase 11:
+- API keys
+- webhooks
+
+Phase 12:
+- feature flags
+- storage
+- observability
+
+---
+
+# Definition of Done
+
+A feature is not complete until:
+
+- TypeScript passes
+- tests pass
+- database migrations are included
+- security boundaries are tested
+- public APIs are documented
+- server/client boundaries are correct
+- no unnecessary infrastructure was introduced
+- the implementation is reusable across multiple SaaS applications
+
+---
+
+# Golden Rule
+
+@digimuza/saas-core should answer:
+
+Who is this user?
+
+What workspace are they in?
+
+What can they do?
+
+What are they entitled to?
+
+What have they paid for?
+
+What is happening?
+
+How do we react to what is happening?
+
+How do we notify the user?
+
+How do we run long-running work?
+
+How do we deliver realtime events?
+
+How do we audit important actions?
+
+Everything else belongs to the individual SaaS application.