tsview/readme.hints.md

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

// 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

// 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