mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:21:09 +02:00
22a73943e1
Final cleanup of references missed in previous rename commits: - Dockerfiles: PUBLIC_MANA_CORE_AUTH_URL → PUBLIC_MANA_AUTH_URL - Go modules: github.com/manacore/* → github.com/mana/* (7 go.mod files) - launchd plists: com.manacore.* → com.mana.* (14 files renamed + content) - Image assets: *_Manacore_AI_Credits* → *_Mana_AI_Credits* (11 files) - .env.example files: ManaCore brand strings → Mana - .prettierignore: stale apps/manacore/* paths → apps/mana/* - Markdown docs (CLAUDE.md, /docs/*): mana-core-auth → mana-auth, etc. Excluded from rename: .claude/, devlog/, manascore/ (historical content), client testimonials, blueprints, npm package refs (@mana-core/*). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
195 lines
6.2 KiB
Markdown
195 lines
6.2 KiB
Markdown
# Chat Project Guide
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/chat/
|
|
├── apps/
|
|
│ ├── server/ # Hono/Bun compute server (@chat/server)
|
|
│ ├── landing/ # Astro marketing landing page (@chat/landing)
|
|
│ ├── web/ # SvelteKit web application (@chat/web)
|
|
│ └── mobile/ # Expo/React Native mobile app (@chat/mobile)
|
|
├── packages/
|
|
│ └── chat-types/ # Shared TypeScript types (@chat/types)
|
|
└── package.json
|
|
```
|
|
|
|
## Commands
|
|
|
|
### Root Level
|
|
|
|
```bash
|
|
pnpm chat:dev # Run all chat apps
|
|
pnpm dev:chat:mobile # Start mobile app
|
|
pnpm dev:chat:web # Start web app
|
|
pnpm dev:chat:landing # Start landing page
|
|
pnpm dev:chat:server # Start server
|
|
pnpm dev:chat:local # Start web + sync (no auth needed)
|
|
pnpm dev:chat:full # Start server + web + auth together
|
|
```
|
|
|
|
### Mobile App (chat/apps/mobile)
|
|
|
|
```bash
|
|
pnpm dev # Start Expo dev server
|
|
pnpm ios # Run on iOS simulator
|
|
pnpm android # Run on Android emulator
|
|
pnpm build:dev # Build development version
|
|
pnpm build:preview # Build preview version
|
|
pnpm build:prod # Build production version
|
|
```
|
|
|
|
### Server (apps/chat/apps/server)
|
|
|
|
```bash
|
|
pnpm start: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:seed # Seed AI models
|
|
pnpm db:studio # Open Drizzle Studio
|
|
```
|
|
|
|
### Web App (chat/apps/web)
|
|
|
|
```bash
|
|
pnpm dev # Start dev server
|
|
pnpm build # Build for production
|
|
pnpm preview # Preview production build
|
|
```
|
|
|
|
### Landing Page (chat/apps/landing)
|
|
|
|
```bash
|
|
pnpm dev # Start dev server
|
|
pnpm build # Build for production
|
|
pnpm preview # Preview production build
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
- **Mobile**: React Native 0.76.7 + Expo SDK 52, NativeWind, Expo Router
|
|
- **Web**: SvelteKit 2.x, Svelte 5, Tailwind CSS 4
|
|
- **Landing**: Astro 5.16, Tailwind CSS
|
|
- **Server**: Hono + Bun, OpenRouter AI + mana-llm (local), Drizzle ORM, PostgreSQL
|
|
- **Auth**: Mana Auth (JWT)
|
|
- **Types**: TypeScript 5.x
|
|
|
|
## Architecture
|
|
|
|
### Server API Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
| --------------------------------- | ------ | --------------------------- |
|
|
| `/api/v1/health` | GET | Health check |
|
|
| `/api/v1/chat/models` | GET | List available AI models |
|
|
| `/api/v1/chat/completions` | POST | Create chat completion |
|
|
| `/api/v1/conversations` | GET | List user conversations |
|
|
| `/api/v1/conversations/:id` | GET | Get conversation details |
|
|
| `/api/v1/conversations/:id/messages` | GET | Get conversation messages |
|
|
| `/api/v1/conversations` | POST | Create new conversation |
|
|
| `/api/v1/conversations/:id/messages` | POST | Add message to conversation |
|
|
|
|
### Environment Variables
|
|
|
|
#### Server (.env)
|
|
|
|
```env
|
|
# Cloud AI models via OpenRouter (optional if using only local models)
|
|
OPENROUTER_API_KEY=sk-or-v1-xxx # Get at https://openrouter.ai/keys
|
|
|
|
# Local AI via mana-llm service
|
|
MANA_LLM_URL=http://localhost:3025 # mana-llm service URL
|
|
LLM_TIMEOUT=120000 # Timeout in ms (default: 120s)
|
|
|
|
# Database (uses shared Docker PostgreSQL)
|
|
DATABASE_URL=postgresql://mana:devpassword@localhost:5432/chat
|
|
|
|
# Auth
|
|
MANA_AUTH_URL=http://localhost:3001
|
|
|
|
# Server
|
|
PORT=3002
|
|
```
|
|
|
|
#### Mobile (.env)
|
|
|
|
```env
|
|
EXPO_PUBLIC_MANA_AUTH_URL=http://localhost:3001
|
|
EXPO_PUBLIC_BACKEND_URL=http://localhost:3002
|
|
```
|
|
|
|
#### Web (.env)
|
|
|
|
```env
|
|
PUBLIC_MANA_AUTH_URL=http://localhost:3001
|
|
PUBLIC_BACKEND_URL=http://localhost:3002
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
- **TypeScript**: Strict typing with interfaces
|
|
- **Mobile**: Functional components with hooks
|
|
- **Web**: Svelte 5 runes mode
|
|
- **Styling**: Tailwind CSS everywhere
|
|
- **Formatting**: 100 char line limit, 2 space tabs, single quotes
|
|
|
|
## AI Models Available
|
|
|
|
### Local Models (Ollama - Free, runs on Mac Mini)
|
|
|
|
| Model ID | Name | Best For |
|
|
| -------- | ---- | -------- |
|
|
| ...440101 | Gemma 3 4B (Lokal) | Everyday tasks (default) |
|
|
| ...440102 | Qwen2.5 Coder 7B (Lokal) | Code generation (92.7% HumanEval) |
|
|
| ...440103 | LLaVA 7B Vision (Lokal) | Image/screenshot analysis |
|
|
| ...440104 | Qwen3 VL 4B (Lokal) | Fast image analysis |
|
|
| ...440105 | DeepSeek OCR (Lokal) | Text recognition in images |
|
|
| ...440106 | Phi 3.5 (Lokal) | Compact, efficient |
|
|
| ...440107 | Ministral 3B (Lokal) | Very fast, simple tasks |
|
|
|
|
### Cloud Models (OpenRouter - Paid)
|
|
|
|
| Model ID | Name | Price | Best For |
|
|
| -------- | ---- | ----- | -------- |
|
|
| ...440201 | Llama 3.1 8B | $0.05/M | Fast cloud alternative |
|
|
| ...440202 | Llama 3.1 70B | $0.35/M | Complex reasoning |
|
|
| ...440203 | DeepSeek V3 | $0.14/M | Reasoning at low cost |
|
|
| ...440204 | Mistral Small | $0.10/M | General tasks |
|
|
| ...440205 | Claude 3.5 Sonnet | $3/M | Best quality |
|
|
| ...440206 | GPT-4o Mini | $0.15/M | Balanced performance |
|
|
|
|
### Adding New Local Models
|
|
|
|
```bash
|
|
# Add new models to existing database
|
|
pnpm --filter @chat/server db:add-local-models
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. **Get OpenRouter API key** at https://openrouter.ai/keys
|
|
2. **Create `.env`** in `apps/chat/apps/server/`:
|
|
```env
|
|
OPENROUTER_API_KEY=sk-or-v1-xxx
|
|
DATABASE_URL=postgresql://mana:devpassword@localhost:5432/chat
|
|
MANA_AUTH_URL=http://localhost:3001
|
|
PORT=3002
|
|
```
|
|
3. **Start services**:
|
|
```bash
|
|
pnpm docker:up # Start PostgreSQL
|
|
pnpm dev:chat:full # Start auth + backend + web
|
|
```
|
|
4. **Seed database** (first time only):
|
|
```bash
|
|
pnpm --filter @chat/server db:push
|
|
pnpm --filter @chat/server db:seed
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
1. **Security**: API keys are stored in the server only - never in client apps
|
|
2. **Authentication**: Uses Mana Auth (JWT tokens)
|
|
3. **Database**: PostgreSQL with Drizzle ORM (uses shared Docker container)
|
|
4. **Deployment**: Server runs on port 3002
|