App Building Patterns - Lossless Ecosystem

This document captures architectural patterns and conventions used across the lossless ecosystem, based on analysis of stack.gallery, serve.zone/onebox, idp.global, and uptime.link projects.

Runtime & Build System

• Deno preferred for new projects (stack.gallery, onebox)
• Node.js for legacy/complex projects (idp.global)
• Build tools: @git.zone/tsbuild, @git.zone/tsbundle, @git.zone/tswatch
• Package manager: pnpm exclusively

Project Structure Pattern

project/
├── ts/                 # Backend TypeScript
│   ├── index.ts       # Entry/exports
│   ├── plugins.ts     # Centralized dependency imports
│   ├── classes/       # Core business logic classes
│   ├── models/        # Database models (SmartData)
│   ├── services/      # Service layer
│   └── api/           # API handlers
├── ui/                 # Angular 19 frontend (Deno projects)
├── ts_web/            # Web components (Node projects)
│   ├── elements/      # Web components
│   ├── pages/         # Page templates
│   ├── interfaces/    # Local interfaces
│   ├── styles/        # Shared styles
│   └── index.ts       # Public exports
├── ts_interfaces/     # Shared TypeScript interfaces
├── mod.ts             # Deno entry point
├── cli.js             # Node.js entry point
└── deno.json/package.json

Core Framework Stack

Layer	Technology
Database	MongoDB via @push.rocks/smartdata
HTTP Server (Deno)	Native Deno.serve()
HTTP Server (Node)	@api.global/typedserver
RPC	@api.global/typedrequest for type-safe client-server
WebSocket	@api.global/typedsocket
State	@push.rocks/smartstate (RxJS-based)

Frontend Patterns

Deno Projects (stack.gallery, onebox)

• Angular 19 with zoneless change detection
• Tailwind CSS for styling
• Standalone components (no NgModules)

Node Projects (idp.global, uptime.link)

• Web Components via @design.estate/dees-element (LitElement wrapper)
• UI components from @design.estate/dees-catalog
• State management via @push.rocks/smartstate with RxJS

Web Component Pattern

@customElement('element-name')
export class ElementName extends DeesElement {
  @property() accessor propertyName: type;

  public static styles = [cssManager.defaultStyles, css`...`];
  public render(): TemplateResult { return html`...`; }
}

Key Dependencies (@push.rocks ecosystem)

Package	Purpose
smartdata	MongoDB ORM with decorators
smartacme	Let's Encrypt/ACME certificates
smartjwt	JWT handling
smartlog	Structured logging
smartenv/qenv	Environment configuration
smartpromise	Promise utilities
smartrx	RxJS utilities
smartstate	State management
smartunique	UUID generation
taskbuffer	Task scheduling
smartnetwork	Network operations
smarturl	URL parsing

Architectural Patterns

1. Manager Pattern: Main orchestrator class with specialized managers

   class MainApp {
     public userManager = new UserManager(this);
     public authManager = new AuthManager(this);
     // ...
   }
   

2. Repository Pattern: Database access via repositories

   class UserRepository extends BaseRepository<User> {
     // CRUD methods
   }
   

3. Plugin Injection: All deps imported via plugins.ts

   // ts/plugins.ts
   import * as smartdata from '@push.rocks/smartdata';
   export { smartdata };
   
   // Usage: plugins.smartdata.Collection(...)
   

4. Type-Safe RPC: TypedRequest/TypedRouter for API

   typedrouter.addHandler(requestInterface, handler);
   

5. Lazy Database: @Collection(() => db) decorator pattern

Deployment

• Deno: Compile to single binary with embedded UI
• Docker: Multi-stage builds (build → production → alpine)
• Systemd: Integration via @push.rocks/smartdaemon

Design Tokens (catalog)

• Fonts: Geist Sans/Mono
• Status colors: operational, degraded, partial, major, maintenance
• Spacing scale: xs(4px) to 4xl(96px)
• Shadow system, border radius tokens
• Dark/light mode via cssManager.bdTheme()

React Alternative (about.uptime.link)

For marketing/info sites:

• React 18 + Vite for build
• Radix UI for accessible components
• TanStack React Query for data fetching
• React Hook Form + Zod for forms
• Tailwind CSS + PostCSS

Testing

• Framework: @git.zone/tstest with @git.zone/tstest/tapbundle as reporter framework. It simply is imported in testfiles: e.g. ./test/test.some.ts would say import {tap, expect} from '@git.zone/tstest/tapbundle' and tap.test('some description', async (toolsArg) => { await expect(someValue)}).toEqual(expectedValue) })
• File patterns: *.ts (Node), *.browser.ts (browser-specific)
• Command: tstest test/ --verbose
• Type checking: tsbuild check test/**/* --skiplibcheck (test only)