managarten/apps/zitare/CLAUDE.md

Zitare Project Guide

Project Structure

apps/zitare/
├── apps/
│   ├── backend/      # NestJS API server (@zitare/backend)
│   ├── landing/      # Astro marketing landing page (@zitare/landing)
│   ├── web/          # SvelteKit web application (@zitare/web)
│   └── mobile/       # Expo/React Native mobile app (@zitare/mobile)
├── packages/
│   ├── shared/       # Shared types, utils, configs (@zitare/shared)
│   ├── content/      # Quote data and content (@zitare/content)
│   └── web-ui/       # Shared Svelte components (@zitare/web-ui)
└── package.json

Commands

Root Level (from monorepo root)

pnpm zitare:dev                   # Run all zitare apps
pnpm dev:zitare:mobile            # Start mobile app
pnpm dev:zitare:web               # Start web app
pnpm dev:zitare:landing           # Start landing page
pnpm dev:zitare:backend           # Start backend server
pnpm dev:zitare:app               # Start web + backend together

Mobile App (apps/zitare/apps/mobile)

pnpm dev                         # Start Expo dev server
pnpm ios                         # Run on iOS simulator
pnpm android                     # Run on Android emulator

Backend (apps/zitare/apps/backend)

pnpm dev                         # Start with hot reload
pnpm build                       # Build for production
pnpm start:prod                  # Start production server
pnpm db:push                     # Push schema to database
pnpm db:studio                   # Open Drizzle Studio

Web App (apps/zitare/apps/web)

pnpm dev                         # Start dev server
pnpm build                       # Build for production
pnpm preview                     # Preview production build

Landing Page (apps/zitare/apps/landing)

pnpm dev                         # Start dev server
pnpm build                       # Build for production

Technology Stack

• Mobile: React Native 0.81 + Expo SDK 54, NativeWind, Expo Router, Zustand
• Web: SvelteKit 2.x, Svelte 5 (runes mode), Tailwind CSS
• Landing: Astro 5.x, Tailwind CSS
• Backend: NestJS 10, Drizzle ORM, PostgreSQL
• Types: TypeScript 5.x

Architecture

Content Delivery (Hybrid)

• Static Content: Quotes and authors are bundled in @zitare/content package for offline access
• Backend API: User-specific data (favorites, lists) are stored in PostgreSQL via backend API

Backend API Endpoints

Endpoint	Method	Description
/api/health	GET	Health check
/api/favorites	GET	Get user's favorites
/api/favorites	POST	Add quote to favorites
/api/favorites/:quoteId	DELETE	Remove from favorites
/api/lists	GET	Get user's lists
/api/lists	POST	Create new list
/api/lists/:id	GET	Get list details
/api/lists/:id	PUT	Update list
/api/lists/:id	DELETE	Delete list
/api/lists/:id/quotes	POST	Add quote to list
/api/lists/:id/quotes/:quoteId	DELETE	Remove quote from list

Database Schema

favorites - User favorite quotes

• id (UUID) - Primary key
• user_id (UUID) - User reference
• quote_id (VARCHAR) - Reference to static quote ID
• created_at (TIMESTAMP)

user_lists - Custom user lists

• id (UUID) - Primary key
• user_id (UUID) - User reference
• name (TEXT) - List name
• description (TEXT) - Optional description
• quote_ids (JSONB) - Array of quote IDs
• created_at (TIMESTAMP)
• updated_at (TIMESTAMP)

Environment Variables

Backend (.env)

NODE_ENV=development
PORT=3007
DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/zitare
MANA_CORE_AUTH_URL=http://localhost:3001
CORS_ORIGINS=http://localhost:5173,http://localhost:5177,http://localhost:8081

Mobile (.env)

EXPO_PUBLIC_BACKEND_URL=http://localhost:3007
EXPO_PUBLIC_MANA_CORE_AUTH_URL=http://localhost:3001

Web (.env)

PUBLIC_BACKEND_URL=http://localhost:3007
PUBLIC_MANA_CORE_AUTH_URL=http://localhost:3001

Shared Packages

@zitare/shared

• Types: ContentItem, ContentAuthor, Quote, QuoteMetadata
• Utils: Search, filter, random selection functions
• Configs: App configuration

@zitare/content

• Static quote data (German and English)
• Author information with biographies
• Export functions for data access

@zitare/web-ui

• Shared Svelte 5 components
• Styling utilities
• Stores

Code Style Guidelines

• TypeScript: Strict typing with interfaces
• Mobile: Functional components with hooks, Zustand for state
• Web: Svelte 5 runes mode ($state, $derived, $effect)
• Styling: Tailwind CSS / NativeWind
• Formatting: Prettier with project config

Important Notes

1. Offline First: Static content works without backend
2. Authentication: Uses Mana Core Auth (JWT in Authorization header)
3. Database: PostgreSQL with Drizzle ORM
4. Port: Backend runs on port 3007 by default