@epic-flow/collections

Shared RxDB collections for Epic Flow applications.

Overview

This package provides TypeScript type definitions and RxDB collection schemas for all data models used across the Epic Flow ecosystem. It includes comprehensive documentation for:

• Project Management: Tasks, Projects, Milestones, Goals, Time Entries
• Business Operations: Clients, Contacts, Opportunities
• Financial Data: YNAB integration for Accounts, Budgets, Categories, Transactions
• System Data: Organizations, Users, Workspaces, Codebases, Sessions
• Conversations: Message handling, conversation state, AI interactions
• Content: Documents, Templates, Discussions, Approvals

Installation

yarn add @epic-flow/collections

Usage

Import collection definitions and types:

import {
  TaskCollection,
  TaskModel,
  ProjectCollection,
  ProjectModel,
  collections
} from '@epic-flow/collections';

// Use individual collection
const taskCollection = TaskCollection;

// Or use collections object
const allCollections = collections;

Documentation

Comprehensive API documentation is generated using TypeDoc and typedoc-plugin-markdown.

Generating Documentation

# Generate HTML documentation
yarn docs

# Generate Markdown documentation
yarn docs:md

# Generate both HTML and Markdown
yarn docs:all

# Watch mode for development (HTML)
yarn docs:watch

# Watch mode for development (Markdown)
yarn docs:md:watch

Documentation Formats

HTML Documentation (docs/)

Interactive HTML documentation with:

• Interface Documentation: All model interfaces with property descriptions
• Type Definitions: Supporting types and enums
• Collection Exports: RxDB collection configurations
• Utility Functions: Helper functions like createId()
• Search Functionality: Full-text search across all documentation
• Dark Mode Support: Automatic theme switching

Viewing HTML Docs:

# On macOS
open docs/index.html

# On Linux
xdg-open docs/index.html

# Or use a local server
npx serve docs

Markdown Documentation (docs-md/)

Markdown documentation for:

• GitHub/GitLab Integration: Renders natively in repository viewers
• Static Site Generators: Compatible with VitePress, Docusaurus, MkDocs, etc.
• Version Control: Easier to track changes in git diffs
• Offline Reading: No web server required

Structure:

• docs-md/README.md - Main index with all types
• docs-md/interfaces/ - Individual interface documentation (44 files)
• docs-md/type-aliases/ - Type alias documentation (7 files)

Viewing Markdown Docs:

# View main index
cat docs-md/README.md

# View specific interface
cat docs-md/interfaces/TaskModel.md

# Or open in your favorite markdown viewer
open docs-md/README.md

Key Features

Multi-Tenant Architecture

All collections include orgId for organization-level data isolation in multi-tenant applications.

Timestamp Management

Collections automatically manage createdAt and updatedAt timestamps with maxLength constraints for RxDB compatibility.

Composite Indexes

Optimized queries with composite indexes on frequently accessed field combinations:

indexes: [
  ['orgId', 'createdAt'],
  ['userId', 'createdAt']
]

Rich Metadata Support

Many collections include flexible metadata fields for extensibility:

• Tasks: MCP agent execution, conversation state, time tracking
• Projects: Planning data, file references, requirement tracking
• Milestones: Acceptance criteria, file tracking
• Messages: Tool calls, AI provider metadata

YNAB Financial Integration

Full support for You Need A Budget (YNAB) financial data:

• Account management
• Budget tracking
• Category organization
• Transaction and scheduled transaction sync

Collection Schemas

All collections use RxDB schema format with:

• Version management (currently version 0)
• Primary keys (typically id)
• JSON Schema validation
• Required fields enforcement
• Custom hooks via defaultHooks()

Development

# Type checking
yarn typecheck

# Build package
yarn build

# Run tests
yarn test

# Generate documentation
yarn docs

Schema Versioning

Collections are currently at version 0. When making breaking schema changes:

1. Increment the version number
2. Add migration strategies if needed
3. Update documentation

Contributing

When adding or modifying collections:

1. Add JSDoc comments to all interfaces and properties
2. Include metadata interfaces if the collection supports extensibility
3. Define composite indexes for common query patterns
4. Export types from src/index.ts
5. Regenerate documentation with yarn docs
6. Verify build with yarn build

License

ISC

Author

Epic Digital Interactive Media LLC