# tsview - Project Hints

## Overview

tsview is a CLI tool for viewing S3 and MongoDB data through a web UI.

## Key Patterns

### Configuration

- Reads from `.nogit/env.json` (created by `gitzone service`)
- Environment variables: MONGODB_URL, S3_HOST, S3_ACCESSKEY, etc.

### CLI Commands

- `tsview` - Start viewer (auto-finds free port from 3010+)
- `tsview --port 3000` - Force specific port
- `tsview s3` - S3 viewer only
- `tsview mongo` - MongoDB viewer only

### Dependencies

- Uses `@push.rocks/smartbucket` for S3 operations
- Uses `@push.rocks/smartdata` for MongoDB operations
- Uses `@api.global/typedserver` + `@api.global/typedrequest` for API
- Uses `@design.estate/dees-catalog` for UI components

### Build Process

- Run `pnpm build` to compile TypeScript and bundle web UI
- UI is bundled from `ts_web/` to `ts/bundled_ui.ts` as base64

### Web UI Structure

- `ts_web/elements/` - Web components (LitElement-based)
- `ts_web/services/` - API service for backend communication
- `ts_web/utilities/` - Shared formatting functions (formatSize, formatCount, getFileName)
- `ts_web/styles/` - Shared CSS custom properties (themeStyles)

### TypedRequest Pattern

```typescript
// Interface definition
export interface IReq_ListBuckets extends plugins.typedrequest.implementsTR<
  plugins.typedrequest.ITypedRequest,
  IReq_ListBuckets
> {
  method: 'listBuckets';
  request: {};
  response: { buckets: string[] };
}

// Handler registration
typedrouter.addTypedHandler(
  new plugins.typedrequest.TypedHandler<IReq_ListBuckets>(
    'listBuckets',
    async (reqData) => {
      return { buckets: [...] };
    }
  )
);
```

## Real-Time Streaming (v1.5.0+)

### Architecture

- `ts/streaming/` - Backend streaming infrastructure
  - `classes.changestream-manager.ts` - Manages MongoDB and S3 watchers
  - `interfaces.streaming.ts` - TypedRequest interfaces for subscriptions
- `ts_web/services/changestream.service.ts` - Frontend WebSocket client

### MongoDB Change Streams

- Uses native MongoDB Change Streams via `SmartdataDb.mongoDbClient`
- Subscription per collection: `db/collection`
- Events: insert, update, delete, replace, drop

### S3 Change Detection

- Uses `@push.rocks/smartbucket` BucketWatcher (polling-based)
- Polling interval: 5 seconds
- Events: add, modify, delete

### Frontend Components

- `tsview-activity-stream.ts` - Combined activity view with filtering
- MongoDB/S3 browsers auto-subscribe to current resource
- Visual indicators for "Live" status and recent change count

### Key Streaming Interfaces

```typescript
// Subscribe to collection changes
IReq_SubscribeMongo: { database, collection } -> { success, subscriptionId }

// Subscribe to bucket changes
IReq_SubscribeS3: { bucket, prefix? } -> { success, subscriptionId }

// Subscribe to activity stream (all changes)
IReq_SubscribeActivity: {} -> { success, subscriptionId }

// Server pushes changes to subscribed clients
IReq_PushMongoChange: { event: IMongoChangeEvent } -> { received }
IReq_PushS3Change: { event: IS3ChangeEvent } -> { received }
IReq_PushActivityEvent: { event: IActivityEvent } -> { received }
```

### Dependencies Added

- `@api.global/typedsocket` - WebSocket client/server
- `@push.rocks/smartrx` - RxJS utilities