# @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

```bash
yarn add @epic-flow/collections
```

## Usage

Import collection definitions and types:

```typescript
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](https://typedoc.org/) and [typedoc-plugin-markdown](https://www.npmjs.com/package/typedoc-plugin-markdown).

### Generating Documentation

```bash
# 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:**
```bash
# 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:**
```bash
# 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:
```typescript
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

```bash
# 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