till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-15 02:01:10 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/apps/mana
History
Till JS f24438f778 feat(mana/web): who module — frontend (game store + UI + routes) 
Client side of the who module. Standard Mana module pattern: types,
collections (Dexie), queries (live), store (mutations), UI components,
routes. Plus three integration points (data layer registries).

Module files
------------
  types.ts
    Two Dexie record interfaces (LocalWhoGame, LocalWhoMessage) and
    matching view types. Server response shapes (WhoChatResponse,
    WhoRandomResponse, WhoGuessResponse) live here too so the store
    and UI both type-check against the same wire contract.

  collections.ts
    Dexie table accessors. No guest seed — the picker handles empty
    state directly.

  queries.ts
    Three liveQueries (allGames$, gameByIdLive, messagesForGameLive)
    that decrypt the encrypted-at-rest fields before returning view
    types. The messages query uses the [gameId+createdAt] composite
    index for ordering. toWhoGame / toWhoMessage converters bridge
    the BaseRecord-extended local types to the public view types.

  module.config.ts
    Standard ModuleConfig: appId='who', tables=[whoGames as 'games',
    whoMessages as 'messages']. The syncName remap means the unified
    Dexie table whoGames syncs to mana-sync's `games` collection
    under appId 'who' — keeps the wire format clean.

  stores/games.svelte.ts
    The mutation surface. Five public methods:
      - start(deckId)        → POST /who/random + insert LocalWhoGame
      - sendMessage(id, txt) → optimistic insert + POST /who/chat +
                               insert NPC reply + (on win) flip status
      - submitGuess(id, txt) → POST /who/guess + (on match) flip
      - surrender(id)        → status=surrendered + finishedAt
      - setNotes(id, notes)  → encrypted post-game notes
      - deleteGame(id)       → soft-delete game + cascade messages
    All writes go through encryptRecord for encrypted-at-rest fields.

UI components
-------------
  ListView.svelte
    Module landing page. Header + 4 deck cards (loaded from
    GET /api/v1/who/decks on mount) + past-games list. Picking a
    deck calls store.start() and navigates to the play view. Past
    games are clickable (read-only for finished games) and
    deletable.

  views/PlayView.svelte
    The chat-loop screen. Header with deck/difficulty + back button
    + Tippen/Aufgeben actions while playing. Scrollable message
    area with bubbles (user purple-tinted, NPC white-tinted).
    Textarea input with Enter-to-send + sending disabled state.
    On reveal: result banner with "Erraten in N Nachrichten!" and
    the resolved name. Post-game: input area swaps to a notes
    textarea with debounced auto-save. Explicit guess modal as
    fallback when the LLM forgets to emit the sentinel.

Routes
------
  /(app)/who                 → ListView wrapper
  /(app)/who/play/[gameId]   → PlayView wrapper, $page.params.gameId

Registry plumbing
-----------------
  database.ts
    Two new Dexie tables in version(1):
      whoGames: 'id, status, deckId, startedAt, finishedAt, [status+startedAt]'
      whoMessages: 'id, gameId, sender, createdAt, [gameId+createdAt]'

  module-registry.ts
    Imports whoModuleConfig and adds to MODULE_CONFIGS. The sync
    engine picks up the appId/table mapping automatically — no
    edits needed in sync.ts.

  crypto/registry.ts
    Two entries:
      whoGames:    { enabled: true, fields: ['revealedName', 'notes'] }
      whoMessages: { enabled: true, fields: ['content'] }
    All other fields stay plaintext for index/sort/filter.

Closes Phase A.2 / A.3 / A.4 / A.5 of docs/WHO_MODULE.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-09 13:10:34 +02:00
..
apps feat(mana/web): who module — frontend (game store + UI + routes) 2026-04-09 13:10:34 +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