Skip to content

README_DEV.md

Latest commit

 

History

History
482 lines (358 loc) · 15.2 KB

README_DEV.md

File metadata and controls

482 lines (358 loc) · 15.2 KB
Raw

All Contributors

BärGPT Dev Documentation

This is the monorepo for BärGPT. You'll find here the frontend, backend, admin-panel and maintenance-mode code.

Table of Contents

🧰 Tech Stack

🎨 Frontend

⚙️ Backend

👥 Admin Panel

🚧 Maintenance Mode

📦 Shared Libraries

  • Database Schema (libs/db-schema): Shared TypeScript types generated from Supabase
  • ESLint Config (libs/eslint): Shared linting rules
  • Prettier Config (libs/prettier): Shared formatting rules
  • TypeScript Config (libs/typescript-config): Shared TypeScript configurations

🏗️ Infrastructure

  • Monorepo Tool: Turborepo
  • Package Manager: npm 11.4.2
  • Node Version: 22.14.0
  • Database & Auth: Supabase (PostgreSQL + Auth + Storage + Realtime)
  • Deployment: Vercel (frontend apps), self-hosted options available (backend)
  • Containerization: Docker (backend)

📋 Prerequisites

Required

🔑 API Keys & Services

You'll need accounts and API keys for:

Required for Backend

  • Mistral AI: API key from https://console.mistral.ai/
  • Gotenberg: URL and credentials for Gotenberg service (PDF conversion)
  • Sentry: DSN from https://sentry.io/ (for error monitoring)
  • Redis: Connection string (for the API rate limiting queue)

Optional for Backend

Optional for Frontend/Admin Panel

  • Matomo: Analytics URL and site ID (for usage tracking)

💿 Installation

# Clone repository
git clone https://github.com/technologiestiftung/baergpt.git
cd baergpt

# Install Node.js version
nvm install && nvm use

# Install dependencies
npm ci

# Install Turborepo globally (optional)
npm install turbo --global

# Install Playwright browsers (for E2E tests)
npx playwright install --with-deps

✅ Setup

1. ⚙️ Backend Setup

Start Local Supabase

cd apps/backend
supabase start

This starts local Supabase services:

⚠️ Save the output - you'll need the anon key, service_role key, and JWT secret.

📡 Enable Database Publications

  1. Open Supabase Studio: http://localhost:54323/project/default/database/publications
  2. Enable the following tables on the Source: document_folders, documents

This enables real-time subscriptions for these tables.

🔧 Configure Backend Environment

cd apps/backend
cp .env.sample .env

Edit .env and fill in the required values. See .env.sample for all available configuration options.

🗄️ Initialize Database

cd apps/backend
npm run db:reset

This resets the database, generates TypeScript types into libs/db-schema/index.ts, and seeds with initial data.

2. 🎨 Frontend Setup

cd apps/frontend
cp .env.sample .env

Edit .env and fill in the required values. See .env.sample for all available configuration options.

3. 👥 Admin Panel Setup

cd apps/admin-panel
cp .env.sample .env

Edit .env and fill in the required values. See .env.sample for all available configuration options.

4. 🚧 Maintenance Mode Setup

No environment configuration needed. This is a static page displayed during maintenance.

💻 Development

Using Turborepo (recommended):

# Run all dev servers
turbo dev

# Run specific apps
turbo dev --filter=frontend --filter=backend
turbo dev --filter=baergpt-frontend

Individual apps:

# Backend (http://localhost:3100)
cd apps/backend && npm run dev

# Frontend (http://localhost:5173)
cd apps/frontend && npm run dev

# Admin Panel (http://localhost:5174)
cd apps/admin-panel && npm run dev

# Maintenance Mode (http://localhost:5175)
cd apps/maintenance-mode && npm run dev

Backend in a container (Docker Compose):

Runs the built backend image (the exact artifact deployed to Cloud Foundry) to validate the container locally. Not for daily coding (use turbo dev for hot reload).

Requires Supabase running first — supabase start from apps/backend. Then, from the repo root:

docker compose up --build  # backend container → http://localhost:3000
docker compose down        # stop and remove the container when done

Supabase stays on the CLI; the container reaches it via host.docker.internal. No hot reload — re-run with --build to pick up code changes.

🧪 Tests

Run all tests from root:

turbo test        # All unit tests
turbo test:e2e    # All E2E tests

Run tests per application:

# Backend (Unit/Integration)
cd apps/backend
npm run test
npm run test:watch  # Watch mode

# Frontend (E2E requires Supabase + backend running)
cd apps/frontend
npm run test        # Unit tests
npm run test:e2e    # E2E tests
npm run test:a11y   # Accessibility tests

# Admin Panel
cd apps/admin-panel
npm run test:e2e

# Maintenance Mode
cd apps/maintenance-mode
npm run test:e2e

🔍 Linting & Formatting

# From root
turbo lint:check      # Check linting
turbo lint:write      # Fix linting issues
npm run prettier:write # Check formatting
npm run prettier:check # Fix formatting issues
turbo check-types     # Type check all packages

🏗️ Building for Production

# Build all apps
turbo build

# Build specific app
cd apps/[app-name]
npm run build

# Backend with Sentry source maps
cd apps/backend
npm run build:prod

Build output locations:

  • Frontend: apps/frontend/dist
  • Backend: apps/backend/dist
  • Admin Panel: apps/admin-panel/dist
  • Maintenance Mode: apps/maintenance-mode/dist

🗄️ Database Management

All database commands should be run from apps/backend:

cd apps/backend

# Reset database to initial migration state
npm run db:reset

# Regenerate TypeScript types after schema changes
npm run db:typegen

# Seed database only
npm run db:localseed

# Lint database for common issues
npm run lint:db

# Create new migration
supabase migration new your_migration_name

# Apply all migrations
supabase db reset

🏠 Self-Hosting Supabase

For production deployments with self-hosted Supabase, see:

  • Guide: infra/README.md
  • Uses: Ansible, 1Password CLI, Docker Compose
  • Cloud Provider: STACKIT (configurable)

🚨 Troubleshooting

Port Conflicts Change ports in respective .env files:

  • Backend: PORT in apps/backend/.env
  • Frontend/Admin Panel: VITE_PORT in .env

Database Issues

cd apps/backend
supabase db reset
npm run db:typegen

Module Not Found

npm ci  # from root

Supabase Connection Failed

cd apps/backend
supabase status  # Check if running

Email Confirmation in Development View test emails at: http://localhost:54324 (Mailpit)

TypeScript Errors After Schema Changes

cd apps/backend
npm run db:typegen

Build Errors

# Clear caches and rebuild from root
rm -rf node_modules apps/*/node_modules libs/*/node_modules
npm ci
turbo build

📁 Project Structure

baergpt/
├── apps/
│   ├── frontend/          # Main user-facing React app
│   ├── backend/           # Hono API + Supabase migrations
│   ├── admin-panel/       # Admin management interface
│   └── maintenance-mode/  # Maintenance page
├── libs/
│   ├── db-schema/         # Generated Supabase types
│   ├── eslint/            # Shared ESLint config
│   ├── prettier/          # Shared Prettier config
│   └── typescript-config/ # Shared TS configs
├── docs/
│   └── adr/               # Architecture Decision Records
├── .nvmrc                 # Node version
├── turbo.json            # Turborepo configuration
└── package.json          # Root workspace config

Contributing

Before you create a pull request, write an issue so we can discuss your changes.

Credits

Made by

Link to the CityLAB Berlin website 		A project by

Link to the Technologiestiftung Berlin website 		Supported by

Link to the Senate Chancellery of Berlin