till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-16 07:59:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/apps/mana
History
Till JS 3b5d58ecbe feat(shared-llm): Phase 4 — persistent LLM task queue 
Until now, modules wanting to use the orchestrator had to await each
LLM call inline in their store code. That's fine for foreground tasks
("user clicked summarize") but a non-starter for background work
("auto-tag every new note", "generate a title for every voice memo
after STT finishes"). Background tasks need to:

  - Queue up while no LLM tier is ready, then drain when one becomes
    available (e.g. user just enabled the browser tier from settings)
  - Survive page reloads, browser restarts, and the user navigating
    away mid-execution
  - Run one at a time without blocking the foreground UI
  - Allow modules to subscribe to results reactively without polling
  - Retry transient failures (network, model loading) but not
    semantic ones (tier-too-low, content blocked)

Phase 4 ships exactly that.

Architecture:

  packages/shared-llm/src/queue.ts — LlmTaskQueue class
    + QueuedTask interface (the persistent row shape)
    + EnqueueOptions (refType/refId/priority/maxAttempts)
    + TaskRegistry type (name → LlmTask map)
    + LlmTaskQueueOptions (table + orchestrator + registry +
                           retryBackoffMs + idleWakeupMs)

  Public API:
    - enqueue(task, input, opts) → string  (returns the queued id)
    - get(id), list(filter)
    - retry(id), cancel(id), purge(olderThanMs)
    - start(), stop()  (idempotent processor lifecycle)

  apps/mana/apps/web/src/lib/llm-queue.ts — web app singleton
    - Dedicated `mana-llm-queue` Dexie database (separate from the
      main `mana` IDB; see comment for the rationale: ephemeral
      per-device state, no encryption needed, no sync needed, doesn't
      belong in the long-frozen `mana` schema)
    - Wires up the queue with llmOrchestrator + taskRegistry
    - Exposes startLlmQueue() / stopLlmQueue() for the layout hook

  apps/mana/apps/web/src/lib/llm-task-registry.ts
    - Maps task names → task objects so the queue processor can
      look up the implementation when pulling rows off the table.
      Closures can't be persisted, so we round-trip via name.
    - Currently registers extractDateTask + summarizeTextTask;
      module-side tasks land here as we add them.

  apps/mana/apps/web/src/routes/(app)/+layout.svelte
    - startLlmQueue() in handleAuthReady's Phase A (auth-independent)
      so guests + authenticated users both get the queue
    - stopLlmQueue() in onDestroy as a fire-and-forget cleanup

Processor loop semantics (the heart of the implementation):

  1. On start(), reclaim any 'running' rows from a crashed previous
     session — reset them to 'pending'. The orphan recovery is the
     reason a crash mid-task doesn't leave the queue stuck.
  2. findNextRunnable() picks the highest-priority pending task whose
     `notBefore` (retry-backoff timestamp) is in the past. Sort key:
     priority desc, then enqueuedAt asc (FIFO within priority).
  3. Mark the task running, increment attempts, look up the LlmTask
     in the registry, hand it to orchestrator.run().
  4. On success: mark done, store result + source + finishedAt.
  5. On error:
       - TierTooLowError or ProviderBlockedError → fail immediately,
         no retry. These are not transient — the user's settings or
         the content itself need to change.
       - Anything else → if attempts < maxAttempts, reset to pending
         with notBefore = now + retryBackoffMs (default 60s). Else
         mark failed.
  6. When no work is pending, sleep on a Promise that resolves when
     either (a) someone calls enqueue() (which fires notifyWakeup),
     or (b) idleWakeupMs elapses (default 30s, safety net for any
     missed wakeup signal).

Module-side reactive reads use Dexie liveQuery directly on the queue
table — no special subscription API on the queue itself. This is
consistent with how every other Mana module reads its data, so the
mental model stays uniform:

  const tags = useLiveQuery(
    () => llmQueueDb.tasks
      .where({ refType: 'note', refId, taskName: 'common.extractTags' })
      .reverse().first(),
    [refId]
  );

Smoke test: a new "Queue" tab in /llm-test lets you enqueue the
existing extractDate / summarize tasks and watch the live state of
the queue table via liveQuery. The display includes per-row state
badge (pending/running/done/failed), tier source, attempt count,
input/output, and a "Done/failed löschen" button that exercises
purge().

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-09 01:51:20 +02:00
..
apps feat(shared-llm): Phase 4 — persistent LLM task queue 2026-04-09 01:51:20 +02:00
.gitignore feat: rename ManaCore to Mana across entire codebase 2026-04-05 20:00:13 +02:00
CLAUDE.md docs: trim CLAUDE.md files — remove stale + duplicated guidance 2026-04-08 11:59:51 +02:00
README.md chore: complete ManaCore → Mana rename (docs, go modules, plists, images) 2026-04-07 12:26:10 +02:00

README.md

Mana Apps

A unified application ecosystem built on a shared authentication system, supporting multiple branded applications across web and mobile platforms.

Overview

Mana Apps is a monorepo containing web and mobile applications that provide organization management, team collaboration, and credit transfer capabilities. The system supports multiple branded applications (Memoro, Cards, Storyteller, Mana) through a flexible multi-tenant architecture.

Applications

  • Web App (apps/web) - SvelteKit-based web application
  • Mobile App (apps/mobile) - React Native (Expo) app for iOS, Android, and web
  • Landing (apps/landing) - Landing page (planned)

Features

  • 🔐 Unified authentication with Supabase
  • 🏢 Organization management with role-based access
  • 👥 Team collaboration and member management
  • 💰 Mana credit system with transfers and balance tracking
  • 🎨 Multi-brand support with configurable themes
  • 📱 Cross-platform (Web, iOS, Android)
  • 🔄 Real-time updates across all platforms
  • 🧪 Comprehensive testing with Vitest and Playwright

Quick Start

Prerequisites

  • Node.js 20+
  • pnpm (for web app)
  • npm (for mobile app)
  • Supabase account with project configured
  • Expo CLI (for mobile development)

Setup

  1. Clone the repository

    git clone <repository-url>
cd mana-core-apps

  2. Web App Setup

    cd apps/web
pnpm install
cp .env.example .env
# Edit .env with your Supabase credentials
pnpm dev

  3. Mobile App Setup

    cd apps/mobile
npm install
cp .env.example .env
# Edit .env with your Supabase credentials
npm start

Project Structure

mana-core-apps/
├── apps/
│   ├── web/                    # SvelteKit web application
│   │   ├── src/
│   │   │   ├── routes/        # File-based routing
│   │   │   │   ├── (auth)/    # Public auth pages
│   │   │   │   └── (app)/     # Protected pages
│   │   │   ├── lib/
│   │   │   │   ├── components/
│   │   │   │   ├── config/    # Multi-app configuration
│   │   │   │   ├── server/    # Server-only utilities
│   │   │   │   └── types/
│   │   │   └── hooks.server.ts # Auth middleware
│   │   └── package.json
│   │
│   ├── mobile/                 # React Native (Expo) app
│   │   ├── app/               # File-based routing (Expo Router)
│   │   │   ├── (drawer)/      # Drawer navigation
│   │   │   ├── auth/          # Auth screens
│   │   │   └── _layout.tsx    # Root layout with auth
│   │   ├── components/        # React components
│   │   ├── utils/            # Utilities (Supabase, storage)
│   │   └── package.json
│   │
│   └── landing/               # Landing page (planned)
│
├── CLAUDE.md                  # Developer documentation
└── README.md                  # This file

Technology Stack

Web App (apps/web)

Category Technology
Framework SvelteKit 2 with Svelte 5 (Runes)
Language TypeScript
Styling TailwindCSS 3 with PostCSS
Database Supabase (PostgreSQL)
Auth Supabase Auth with SSR
Testing Vitest (unit) + Playwright (E2E)
Build Tool Vite

Mobile App (apps/mobile)

Category Technology
Framework Expo 52 with React Native 0.76
Language TypeScript
Routing Expo Router 4 (file-based)
Styling NativeWind (TailwindCSS for RN)
Navigation React Navigation (drawer, tabs)
Database Supabase
Build EAS Build
Platforms iOS, Android, Web

Development

Web App Commands

cd apps/web

# Development
pnpm dev                # Start dev server (http://localhost:5173)
pnpm build              # Build for production
pnpm preview            # Preview production build

# Code Quality
pnpm check              # Type-check with svelte-check
pnpm check:watch        # Type-check in watch mode
pnpm lint               # Check formatting and lint
pnpm format             # Format code with Prettier

# Testing
pnpm test               # Run unit tests (Vitest)
pnpm test:ui            # Run tests with UI
pnpm test:e2e           # Run E2E tests (Playwright)

Mobile App Commands

cd apps/mobile

# Development
npm start               # Start Expo dev server
npm run ios             # Run on iOS simulator
npm run android         # Run on Android emulator
npm run web             # Run web version (http://localhost:19006)

# Building
npm run build:dev       # Build dev client
npm run build:preview   # Build for internal testing
npm run build:prod      # Build for production

# Code Quality
npm run lint            # Lint and check formatting
npm run format          # Fix linting and format code

# Setup
npm run prebuild        # Generate native projects

Environment Configuration

Both apps require Supabase configuration. Create .env files based on .env.example:

Web App (apps/web/.env)

PUBLIC_SUPABASE_URL=your_supabase_project_url
PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
MIDDLEWARE_URL=https://mana-middleware-111768794939.europe-west3.run.app
PUBLIC_APP_NAME=Mana Web
NODE_ENV=development

Mobile App (apps/mobile/.env)

EXPO_PUBLIC_SUPABASE_URL=your_supabase_project_url
EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Architecture

Multi-Tenant System

The system supports multiple branded applications sharing the same authentication backend:

  • Memoro - Voice recordings and memory management
  • Cards - AI-powered flashcard learning
  • Storyteller - Creative writing with AI assistance
  • Mana - Central account and organization management

App configurations are centralized in apps/web/src/lib/config/apps.ts, defining branding, features, and routing for each application.

Authentication Flow

Web (SvelteKit):

  1. Server-side authentication using @supabase/ssr
  2. Middleware in hooks.server.ts handles session validation
  3. Protected routes in (app) group require authentication
  4. JWT validation via safeGetSession() before allowing access

Mobile (Expo):

  1. Client-side authentication using @supabase/supabase-js
  2. Custom memory storage for session persistence
  3. AuthProvider in app/_layout.tsx manages auth state
  4. Automatic navigation based on authentication status

Database Schema

Key tables:

  • users - User profiles (linked via auth_id to Supabase Auth)
  • organizations - Organization entities
  • user_roles - User-organization relationships with roles
  • teams - Team entities within organizations
  • team_members - User-team memberships
  • credit_transactions - Mana credit transfer history

See CLAUDE.md for detailed architecture documentation.

Testing

Web App

cd apps/web

# Unit tests
pnpm test              # Run all tests
pnpm test:ui           # Open Vitest UI

# E2E tests
pnpm test:e2e          # Run Playwright tests
pnpm test:e2e --ui     # Run with Playwright UI

Mobile App

Mobile testing is primarily done through Expo Go or development builds:

cd apps/mobile
npm start              # Start dev server
# Then press 'i' for iOS or 'a' for Android

Deployment

Web App

Vercel (Recommended):

cd apps/web
vercel

Netlify:

cd apps/web
netlify deploy

Mobile App

iOS and Android (via EAS):

cd apps/mobile

# Preview build (internal testing)
npm run build:preview

# Production build
npm run build:prod

Configure EAS in eas.json with your build profiles.

Contributing

  1. Create a feature branch from main
  2. Make your changes
  3. Run linting and tests
  4. Submit a pull request

Code Style

  • Use TypeScript for type safety
  • Follow ESLint and Prettier configurations
  • Write tests for new features
  • Use conventional commit messages

Documentation

  • CLAUDE.md - Comprehensive developer guide for Claude Code
  • apps/web/README.md - Web-specific documentation
  • Individual component documentation in source files

Support

For questions or issues, please contact the development team or open an issue in the repository.

License

Private - All rights reserved