till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 19:01:08 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

chore: remove all NestJS backend references, replace with Hono/Bun

Browse source 
- Delete nestjs-backend.md guideline (replaced by hono-server.md)
- Delete Dockerfile.nestjs-base and Dockerfile.nestjs templates
- Delete stale BACKEND_ARCHITECTURE.md doc (NestJS-era, obsolete)
- Update CLAUDE.md, GUIDELINES.md, authentication.md to Hono/Bun first
- Update all app CLAUDE.md files: backend/ → server/, NestJS → Hono+Bun
- Update all app package.json files: @*/backend → @*/server
- Update docs: LOCAL_DEVELOPMENT, PORT_SCHEMA, ENVIRONMENT_VARIABLES,
  DATABASE_MIGRATIONS, MAC_MINI_SERVER, PROJECT_OVERVIEW
- Update scripts: generate-env.mjs, setup-databases.sh, build-app.sh
- Update CI/CD: cd-macmini.yml backend → server paths
- Update Astro docs site: @chat/backend → @chat/server

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Till JS 2026-03-31 16:52:25 +02:00
parent 708299b35e
commit ab387b9b3d
43 changed files with 598 additions and 2398 deletions
Download patch file Download diff file Expand all files Collapse all files

296
docs/LOCAL_DEVELOPMENT.md
View file

@ -1,35 +1,94 @@
# Local Development Guide
This guide explains how to set up and run applications locally with automatic database setup.
This guide explains how to set up and run applications locally. All apps use a **local-first architecture** with IndexedDB (Dexie.js) for reads/writes and mana-sync for background synchronization. Server-side compute (AI, file operations, RRULE expansion, etc.) is handled by lightweight **Hono/Bun servers**.
## Quick Start
For any project with a backend, use the `dev:*:full` command:
### Fastest: `dev:*:local` (recommended for daily development)
No auth service needed. Starts mana-sync + server (if any) + web:
```bash
pnpm dev:chat:full # Start chat with auth + database setup
pnpm dev:zitare:full # Start zitare with auth + database setup
pnpm dev:contacts:full # Start contacts with auth + database setup
# ... etc
pnpm dev:todo:local # sync + server + web
pnpm dev:chat:local # sync + server + web
pnpm dev:zitare:local # sync + web (no server needed)
pnpm dev:clock:local # sync + web (no server needed)
```
Guest mode works out of the box -- data lives in IndexedDB, no login required.
### Full stack: `dev:*:full` (with auth + database setup)
Use this when you need authentication, cross-device sync, or to test the full production flow:
```bash
pnpm dev:todo:full # DB setup + auth + sync + server + web
pnpm dev:chat:full # DB setup + auth + sync + server + web
pnpm dev:zitare:full # auth + sync + web
pnpm dev:calendar:full # DB setup + auth + sync + server + web
```
These commands automatically:
1. Create the database if it doesn't exist
2. Push the latest schema (Drizzle `db:push`)
3. Start the auth service (mana-core-auth)
4. Start the backend and web app with colored output
1. Create the database if it doesn't exist (for apps with Drizzle schemas)
2. Push the latest schema (`drizzle-kit push --force`)
3. Start the auth service (mana-auth)
4. Start mana-sync (Go WebSocket server)
5. Start the Hono/Bun server (if the app has one)
6. Start the web app with colored output
## Available Full Dev Commands
## Available Dev Commands
| Command | Database | Backend Port | Web Port |
|---------|----------|--------------|----------|
| `pnpm dev:chat:full` | chat | 3002 | 5173 |
| `pnpm dev:zitare:full` | zitare | 3007 | 5177 |
| `pnpm dev:contacts:full` | contacts | 3015 | 5184 |
| `pnpm dev:calendar:full` | calendar | 3014 | 5179 |
| `pnpm dev:clock:full` | clock | 3017 | 5187 |
| `pnpm dev:todo:full` | todo | 3018 | 5188 |
| `pnpm dev:picture:full` | picture | 3006 | 5175 |
### Apps with Hono/Bun Servers
These apps have server-side compute and support both `local` and `full` modes:
| App | Server Port | Web Port | `local` | `full` |
|-----|-------------|----------|---------|--------|
| Todo | 3019 | 5188 | Yes | Yes |
| Chat | 3002 | 5174 | Yes | Yes |
| Calendar | 3003 | 5179 | Yes | Yes |
| Contacts | 3004 | 5184 | Yes | Yes |
| Picture | 3006 | 5175 | Yes | Yes |
| ManaDeck | 3009 | 5176 | Yes | Yes |
| Mukke | 3010 | 5180 | Yes | Yes |
| Questions | 3011 | 5111 | Yes | Yes |
| Storage | 3016 | 5185 | Yes | Yes |
| Context | 3020 | 5192 | Yes | Yes |
| Planta | 3022 | 5191 | Yes | Yes |
| NutriPhi | 3023 | 5180 | Yes | Yes |
| Traces | 3026 | mobile | Yes | Yes |
| Presi | 3008 | 5178 | Yes | Yes |
| uLoad | 3070 | 5173 | Yes | Yes |
| News | 3071 | 5173 | Yes | Yes |
| WiseKeep | 3072 | 5173 | Yes | Yes |
| Moodlit | 3073 | 5173 | Yes | Yes |
### Apps without Servers (sync + web only)
These apps use only IndexedDB + mana-sync, no server-side compute:
| App | Web Port | `local` | `full` |
|-----|----------|---------|--------|
| Zitare | 5107 | Yes | Yes |
| Clock | 5187 | Yes | Yes |
| SkilltTree | 5195 | Yes | Yes |
| Photos | 5189 | Yes | Yes |
| CityCorners | 5196 | Yes | Yes |
| Inventar | 5190 | Yes | Yes |
| Times | 5197 | Yes | Yes |
| Calc | 5198 | Yes | Yes |
| ManaVoxel | 5028 | Yes | Yes |
### Infrastructure Ports
| Service | Port | Description |
|---------|------|-------------|
| mana-auth | 3001 | Central auth (Better Auth + EdDSA JWT) |
| mana-sync | 3050 | Data sync (Go, WebSocket, field-level LWW) |
| PostgreSQL | 5432 | Database |
| Redis | 6379 | Cache |
| MinIO API | 9000 | S3-compatible storage |
| MinIO Console | 9001 | Storage web UI |
## Prerequisites
@ -39,41 +98,65 @@ Before running any `dev:*:full` command:
# 1. Start Docker infrastructure (PostgreSQL, Redis, MinIO)
pnpm docker:up
# 2. Generate environment files (runs automatically on pnpm install)
# 2. Build mana-sync (first time only, or after Go changes)
pnpm dev:sync:build
# 3. Generate environment files (runs automatically on pnpm install)
pnpm setup:env
```
For `dev:*:local`, only mana-sync needs to be built. No Docker required unless your server uses a database.
## Database Setup Commands
### Individual Service Setup
```bash
pnpm setup:db:auth # Setup mana-core-auth database + schema
pnpm setup:db:chat # Setup chat database + schema
pnpm setup:db:zitare # Setup zitare database + schema
pnpm setup:db:contacts # Setup contacts database + schema
pnpm setup:db:calendar # Setup calendar database + schema
pnpm setup:db:clock # Setup clock database + schema
pnpm setup:db:todo # Setup todo database + schema
pnpm setup:db:picture # Setup picture database + schema
pnpm setup:db:auth # Setup mana-auth database + schema
pnpm setup:db:chat # Setup chat database + schema
pnpm setup:db:todo # Setup todo database + schema
pnpm setup:db:contacts # Setup contacts database + schema
pnpm setup:db:calendar # Setup calendar database + schema
pnpm setup:db:picture # Setup picture database + schema
pnpm setup:db:uload # Setup uload database + schema
pnpm setup:db:context # Setup context database + schema
pnpm setup:db:storage # Setup storage database + schema
pnpm setup:db:mukke # Setup mukke database + schema
pnpm setup:db:planta # Setup planta database + schema
pnpm setup:db:nutriphi # Setup nutriphi database + schema
pnpm setup:db:questions # Setup questions database + schema
pnpm setup:db:traces # Setup traces database + schema
```
### Setup All Databases
```bash
pnpm setup:db # Creates ALL databases and pushes ALL schemas
pnpm setup:db # Creates ALL databases and pushes ALL schemas
```
This is useful when setting up a fresh environment or after pulling new schema changes.
## How It Works
### Architecture
```
Guest: App -> IndexedDB (Dexie.js) -> UI (no sync)
Logged in: App -> IndexedDB -> UI -> SyncEngine -> mana-sync (Go) -> PostgreSQL
<- WebSocket push <-
```
**mana-sync** (Go, port 3050) handles WebSocket-based sync with field-level last-write-wins conflict resolution. All CRUD goes through IndexedDB first, making the UI instant regardless of network.
**Hono/Bun servers** handle operations that cannot run client-side:
- AI/LLM calls (chat, questions, picture generation)
- File operations (storage, media processing)
- RRULE expansion and reminder scheduling (todo, calendar)
- Server-side data processing (news extraction, transcription)
### Docker Init Script
On first `pnpm docker:up`, the PostgreSQL container runs `docker/init-db/01-create-databases.sql` which creates all databases:
- manacore, chat, zitare, contacts, calendar, clock, todo, manadeck
- storage, mail, moodlit, finance, inventory, techbase, voxel_lava, figgos
On first `pnpm docker:up`, the PostgreSQL container runs `docker/init-db/01-create-databases.sql` which creates all databases.
### Setup Script
@ -84,6 +167,16 @@ The `scripts/setup-databases.sh` script:
The `--force` flag auto-approves schema changes without interactive prompts.
### What each command starts
| Command pattern | What it runs |
|-----------------|-------------|
| `dev:*:local` | mana-sync + server (if any) + web |
| `dev:*:full` | DB setup + mana-auth + mana-sync + server (if any) + web |
| `dev:*:server` | Just the Hono/Bun server (`bun run --watch src/index.ts`) |
| `dev:*:web` | Just the SvelteKit web app |
| `dev:*:app` | Server + web (no sync, no auth) |
## Troubleshooting
### Database doesn't exist
@ -103,17 +196,26 @@ PGPASSWORD=devpassword psql -h localhost -U manacore -d postgres -c "CREATE DATA
If you see errors about missing tables/columns:
```bash
# Push the latest schema
pnpm --filter @chat/backend db:push --force
# Push the latest schema from the server package
pnpm --filter @chat/server db:push --force
```
### mana-sync not built
If you see `./server: No such file or directory`:
```bash
pnpm dev:sync:build
```
### Port already in use
If auth (port 3001) is already running:
If auth (port 3001) or sync (port 3050) is already running:
```bash
# Check what's using the port
lsof -i :3001
lsof -i :3050
# Kill the process if needed
kill <PID>
@ -134,23 +236,6 @@ pnpm docker:up
pnpm setup:db
```
## Apps Without Full Commands
Some apps don't have backends or don't use Drizzle:
| App | Reason |
|-----|--------|
| manacore | No backend (uses other services) |
| manadeck | Backend exists but no db:push |
| bauntown, context, maerchenzauber, memoro, news, nutriphi, presi, quote, reader, storage, wisekeep | No backends |
For these, use the regular dev commands:
```bash
pnpm dev:manacore:web
pnpm dev:manadeck:app
```
## Adding a New Application
### Step 1: Create Project Structure
@ -160,7 +245,7 @@ Create the standard project structure under `apps/`:
```
apps/newproject/
├── apps/
│ ├── backend/ # NestJS API (if needed)
│ ├── server/ # Hono/Bun server (if needed for compute)
│ ├── mobile/ # Expo React Native app
│ ├── web/ # SvelteKit web app
│ └── landing/ # Astro marketing page
@ -170,9 +255,24 @@ apps/newproject/
└── CLAUDE.md # Project documentation
```
### Step 2: Configure Backend Database (if applicable)
### Step 2: Set Up Local-First Data Layer
If your backend uses Drizzle ORM:
1. Create `apps/newproject/apps/web/src/lib/data/local-store.ts` with `createLocalStore()`
2. Create `apps/newproject/apps/web/src/lib/data/guest-seed.ts` for onboarding data
3. Use `collection.getAll()` / `collection.insert()` in stores (not API calls)
4. In layout: `await store.initialize()`, `store.startSync()` on login
### Step 3: Create Hono/Bun Server (if needed)
Only needed if your app requires server-side compute (AI, file ops, etc.).
Create `apps/newproject/apps/server/` with:
- `src/index.ts` -- Hono app entry point
- `src/config.ts` -- Port and env config
- `src/routes/health.ts` -- Health check endpoint
- `package.json` with `"name": "@newproject/server"`
### Step 4: Configure Database (if the server uses Drizzle)
1. **Add database to Docker init** (`docker/init-db/01-create-databases.sql`):
```sql
@ -181,84 +281,59 @@ If your backend uses Drizzle ORM:
```
2. **Add to setup script** (`scripts/setup-databases.sh`):
In the `setup_service()` function, add a new case:
```bash
newproject)
create_db_if_not_exists "newproject"
push_schema "@newproject/backend" "newproject"
push_schema "@newproject/server" "newproject"
;;
```
Also add to the `ALL_DATABASES` array:
```bash
ALL_DATABASES=(
...
"newproject"
)
```
And to the services loop at the bottom:
```bash
for service in auth chat ... newproject; do
```
3. **Add DATABASE_URL to `.env.development`**:
```env
NEWPROJECT_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/newproject
```
4. **Update `scripts/generate-env.mjs`** to generate the backend `.env` file.
4. **Update `scripts/generate-env.mjs`** to generate the server `.env` file.
### Step 3: Add Package.json Scripts
### Step 5: Add Package.json Scripts
Add to root `package.json`:
```json
{
"scripts": {
// Project-level dev (all apps)
"newproject:dev": "turbo run dev --filter=newproject...",
// Individual app commands
"dev:newproject:web": "pnpm --filter @newproject/web dev",
"dev:newproject:mobile": "pnpm --filter @newproject/mobile dev",
"dev:newproject:backend": "pnpm --filter @newproject/backend dev",
"dev:newproject:landing": "pnpm --filter @newproject/landing dev",
"dev:newproject:app": "turbo run dev --filter=@newproject/web --filter=@newproject/backend",
// Full dev with auto database setup
"dev:newproject:full": "./scripts/setup-databases.sh newproject && ./scripts/setup-databases.sh auth && concurrently -n auth,backend,web -c blue,green,cyan \"pnpm dev:auth\" \"pnpm dev:newproject:backend\" \"pnpm dev:newproject:web\"",
// Database shortcuts
"newproject:db:push": "pnpm --filter @newproject/backend db:push",
"newproject:db:studio": "pnpm --filter @newproject/backend db:studio",
// Setup shortcut
"dev:newproject:server": "cd apps/newproject/apps/server && bun run --watch src/index.ts",
"dev:newproject:local": "concurrently -n sync,server,web -c magenta,yellow,cyan \"pnpm dev:sync\" \"pnpm dev:newproject:server\" \"pnpm dev:newproject:web\"",
"dev:newproject:full": "./scripts/setup-databases.sh newproject && ./scripts/setup-databases.sh auth && concurrently -n auth,sync,server,web -c blue,magenta,yellow,cyan \"pnpm dev:auth\" \"pnpm dev:sync\" \"pnpm dev:newproject:server\" \"pnpm dev:newproject:web\"",
"setup:db:newproject": "./scripts/setup-databases.sh newproject"
}
}
```
### Step 4: Create Project CLAUDE.md
For apps **without** a server (sync + web only):
Create `apps/newproject/CLAUDE.md` with:
- Project overview
- Structure diagram
- Available commands
- API endpoints (if backend)
- Environment variables
- Tech stack details
```json
{
"scripts": {
"dev:newproject:web": "pnpm --filter @newproject/web dev",
"dev:newproject:local": "concurrently -n sync,web -c magenta,cyan \"pnpm dev:sync\" \"pnpm dev:newproject:web\"",
"dev:newproject:full": "concurrently -n auth,sync,web -c blue,magenta,cyan \"pnpm dev:auth\" \"pnpm dev:sync\" \"pnpm dev:newproject:web\""
}
}
```
See existing projects like `apps/chat/CLAUDE.md` for reference.
### Step 6: Create Project CLAUDE.md
### Step 5: Test the Setup
Create `apps/newproject/CLAUDE.md` with project overview, structure, commands, and API endpoints.
### Step 7: Test the Setup
```bash
# Create database and push schema
pnpm setup:db:newproject
# Quick start (no auth needed)
pnpm dev:newproject:local
# Start with full dev command
# Full stack (with auth + DB setup)
pnpm dev:newproject:full
```
@ -266,10 +341,13 @@ pnpm dev:newproject:full
- [ ] Create project structure under `apps/newproject/`
- [ ] Add `pnpm-workspace.yaml` in project root
- [ ] Add database to `docker/init-db/01-create-databases.sql`
- [ ] Add service to `scripts/setup-databases.sh`
- [ ] Add DATABASE_URL to `.env.development`
- [ ] Set up local-store with Dexie.js collections
- [ ] Create guest seed data
- [ ] Add Hono/Bun server (if compute needed)
- [ ] Add database to `docker/init-db/01-create-databases.sql` (if using Drizzle)
- [ ] Add service to `scripts/setup-databases.sh` (if using Drizzle)
- [ ] Add DATABASE_URL to `.env.development` (if using Drizzle)
- [ ] Update `scripts/generate-env.mjs` for env generation
- [ ] Add scripts to root `package.json`
- [ ] Create `CLAUDE.md` with project documentation
- [ ] Test with `pnpm dev:newproject:full`
- [ ] Test with `pnpm dev:newproject:local`