Project Structure

Meister Bill is organized as a pnpm monorepo with multiple applications and shared packages.

Repository Layout

.
├── apps/                   # Application packages
│   ├── api/                # Backend API (Hono + Bun)
│   └── web/                # Nuxt 3 frontend (SSR/SSG)
│
├── schemas/                # Shared Zod schemas & types (top-level workspace)
│
├── database/               # Database schema and migrations
│   ├── dumps/              # Database dump files
│   ├── functions/          # Database functions and triggers
│   ├── migrations/         # Database migrations
│   ├── tables/             # SQL table definitions (PostgreSQL)
│   └── templates/          # SQL templates
│
├── docs/                   # 📚 Documentation
│   ├── architecture/       # Architecture deep dives
│   ├── api/                # API documentation
│   ├── features/           # Feature documentation
│   ├── guides/             # How-to guides
│   ├── ideas/              # Future ideas & concepts
│   └── infrastructure/     # Infrastructure docs
│
├── infra/                  # Infrastructure utilities and tools
│   ├── bruno/              # API testing collection
│   ├── docker/             # Docker configurations
│   ├── scripts/            # Deployment scripts
│   ├── gitea/              # CI/CD configuration
│   ├── nginx/              # Nginx configurations
│   ├── openprovider-dns/   # DNS configuration
│   └── scripts/            # Infrastructure scripts
│
├── tests/                  # End-to-end tests
│   └── e2e/                # Playwright E2E tests
│
├── .gitea/                 # Gitea CI/CD workflows
│   └── workflows/
│       └── deploy.yml      # Deployment workflow
│
├── compose.yml             # Docker Compose for local services
├── package.json            # Root package configuration
├── playwright.config.ts    # Playwright E2E configuration
├── pnpm-workspace.yaml     # Workspace configuration
├── AGENTS.md               # AI assistant guidelines
├── CLAUDE.md               # AI coding guidelines
└── README.md               # Project overview

Applications

API (apps/api/)

Backend API built with Hono and Bun

apps/api/
├── src/
│   ├── config/             # Configuration files
│   ├── controllers/        # Business logic controllers
│   ├── middleware/         # Request middleware
│   ├── routes/             # API route handlers
│   ├── services/           # Service layer (EventBus, Email, Stripe, etc.)
│   ├── subscribers/        # Event subscribers (Audit, etc.)
│   ├── tasks/              # Background task handlers
│   ├── templates/          # Email and PDF templates
│   ├── utils/              # Utility functions
│   └── index.ts            # Entry point
├── Dockerfile              # Docker image for deployment
├── package.json
└── tsconfig.json

Key Features: - Hono web framework with Bun runtime - OpenAPI documentation - JWT authentication - Event-driven architecture - Background task processing

See Also: Event Bus Architecture

Web (apps/web/)

Frontend built with Nuxt 3

apps/web/
├── pages/                  # File-based routing
│   ├── index.vue           # Homepage
│   ├── member/             # Protected member routes
│   ├── blog/               # Blog pages
│   └── ...
├── components/             # Vue components
│   ├── forms/              # Reusable form components
│   ├── navigation/         # Navigation components
│   └── ui/                 # UI components
├── composables/            # Composable functions
│   ├── useAuth.ts          # Authentication
│   ├── useEventBus.ts      # Event bus
│   └── ...
├── content/                # Nuxt Content (blog articles)
├── i18n/                   # Internationalization
│   └── locales/
│       ├── en.json
│       └── de.json
├── layouts/                # Page layouts
├── middleware/             # Route middleware
├── modules/                # Nuxt modules
├── public/                 # Static assets
├── nuxt.config.ts          # Nuxt configuration
├── Dockerfile              # Docker image for deployment
└── package.json

Key Features: - SSR/SSG support - Tailwind CSS + DaisyUI - i18n (EN/DE) - Auto-imports - PWA-ready

Shared Packages

Schemas (schemas/)

Centralized Zod V4 schemas for validation

schemas/
├── src/
│   ├── index.ts                    # Main export
│   ├── *Schema.ts                  # Individual schemas
│   ├── *Schema.test.ts             # Schema tests
│   ├── AddressFormatters.ts        # Address formatting utilities
│   ├── CountryNames.ts             # Country code mappings
│   ├── forms/                      # Form validation schemas
│   ├── newsletter/                 # Newsletter schemas
│   └── openapi/                    # OpenAPI schemas
├── dist/                           # Compiled output
└── package.json                    # Published as @meisterbill/schemas

Usage:

import { invoiceSchema, customerSchema } from "@meisterbill/schemas";

See Also: Schema Validation Guide

Database

Tables (database/tables/)

SQL table definitions for PostgreSQL:

database/tables/
├── accounts.sql
├── addresses.sql
├── audit.sql
├── customers.sql
├── documents.sql
├── founder_deal.sql
├── git_commits.sql
├── git_providers.sql
├── git_repositories.sql
├── payments.sql
├── projects.sql
├── service_providers.sql
└── ...

Migrations (database/migrations/)

Database schema migrations with sequential numbering:

database/migrations/
├── 001_initial_schema.sql
├── 002_add_stripe_integration.sql
├── 003_add_payment_history.sql
└── ...

Functions (database/functions/)

Database functions and triggers:

database/functions/
├── handle_new_user.sql         # User signup trigger
└── ...

Other Database Files

  • database/README.md - Database documentation
  • database/schema.sql - Full schema export
  • database/seed.sql - Seed data
  • database/dumps/ - Database dump files
  • database/templates/ - SQL templates

Infrastructure

Bruno (infra/bruno/)

API testing collection organized by feature:

infra/bruno/
├── Founder Deal/           # Founder deal endpoints
├── Authentication/         # Auth endpoints
├── Invoices/               # Invoice endpoints
└── ...

Docker (infra/docker/)

Docker configurations for deployment:

infra/docker/
├── Dockerfile.api          # API Docker image
├── Dockerfile.web          # Web Docker image
└── Dockerfile.gotenberg    # PDF service image

Cloudflare Deployment

Cloudflare Workers and Pages deployment configurations:

API (Cloudflare Workers): - Config: apps/api/wrangler.jsonc - Production: meisterbill-api (api.meister-bill.com) - Staging: meisterbill-api-staging (api-staging.meister-bill.com)

Web (Cloudflare Pages): - Config: apps/web/wrangler.toml - Project: meisterbill-web (www.meister-bill.com)

Docs (Cloudflare Pages): - Project: meisterbill-docs (docs.meister-bill.com)

Other Infrastructure

  • infra/gitea/ - CI/CD configuration for Gitea
  • infra/nginx/ - Nginx reverse proxy configs
  • infra/openprovider-dns/ - DNS zone files
  • infra/scripts/ - Deployment and utility scripts

Testing

E2E Tests (tests/e2e/)

Playwright end-to-end tests:

tests/e2e/
├── fixtures/               # Test fixtures
├── tests/                  # Test files
└── utils/                  # Test utilities

Run with: pnpm e2e

Workspace Configuration

pnpm-workspace.yaml

Defines the monorepo structure:

packages:
  - 'apps/*'
  - 'schemas'

Package Dependencies

Packages reference each other using the workspace:* protocol:

{
  "dependencies": {
    "@meisterbill/schemas": "workspace:*"
  }
}

Documentation

The docs/ directory contains comprehensive documentation:

  • architecture/ - Architecture deep dives
  • api/ - API documentation
  • features/ - Feature documentation
  • guides/ - How-to guides (setup, testing, schema validation)
  • ideas/ - Future ideas (desktop app, escrow, MCP server)
  • infrastructure/ - Infrastructure documentation
  • Root level - Business docs (Briefing, BMC, Launch Strategy, etc.)

All documentation is cross-linked for easy navigation.

See Also