Skip to content

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)
│   ├── app/                # Ionic mobile/desktop client
│   ├── web/                # Nuxt3 frontend (SPA)
│   └── blogwriter/         # Blog content management tool
│
├── schemas/                # Shared Zod schemas & types (top-level workspace)
│
├── packages/               # Shared packages
│   └── core/               # Business logic (e.g., invoice calculations)
│
├── database/               # Database schema and migrations
│   ├── tables/             # SQL table definitions (PostgreSQL)
│   ├── migrations/         # Database migrations
│   └── functions/          # Database functions and triggers
│
├── docs/                   # 📚 Documentation
│   ├── guides/             # How-to guides
│   ├── features/           # Feature documentation
│   ├── architecture/       # Architecture deep dives
│   └── issues/             # Issue implementation docs
│
├── infra/                  # Infrastructure utilities and tools
│   ├── bruno/              # API testing collection
│   └── gitea/              # CI/CD configuration
│
├── .gitea/                 # Gitea CI/CD workflows
│   └── workflows/
│       └── deploy.yml      # Deployment workflow
│
├── pnpm-workspace.yaml     # Workspace configuration
├── package.json            # Root package configuration
├── README.md               # Project overview
├── CLAUDE.md               # AI assistant guidelines
└── CHANGELOG.md            # Version history

Applications

API (apps/api/)

Backend API built with Hono and Bun

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

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

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
│   └── ...
├── composables/            # Composable functions
│   ├── useAuth.ts          # Authentication
│   ├── useEventBus.ts      # Event bus
│   └── ...
├── layouts/                # Page layouts
├── middleware/             # Route middleware
├── plugins/                # Nuxt plugins
├── content/                # Nuxt Content (blog articles)
├── i18n/                   # Internationalization
│   └── locales/
│       ├── en.json
│       └── de.json
├── public/                 # Static assets
├── utils/                  # Utility functions
├── test/                   # Unit tests
├── nuxt.config.ts          # Nuxt configuration
└── package.json

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

App (apps/app/)

Mobile/Desktop app built with Ionic

apps/app/
├── src/
│   ├── views/              # Page components
│   ├── components/         # Reusable components
│   ├── router/             # Vue Router configuration
│   └── App.vue             # Root component
├── capacitor.config.ts     # Capacitor configuration
└── package.json

Key Features: - Cross-platform (iOS, Android, Desktop) - Offline support - Native device APIs - Capacitor integration

Blog Writer (apps/blogwriter/)

Standalone tool for blog content management

Runs independently via ts-node. Used for creating and managing blog articles in apps/web/content/blog/.

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
└── package.json                    # Published as @meisterbill/schemas

Usage:

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

See Also: Schema Validation Guide

Core (packages/core/)

Business logic and calculations

packages/core/
├── src/
│   ├── invoice/            # Invoice calculations
│   └── ...
└── package.json

Example functions: - createInvoice() - Invoice creation logic - calcTotal() - Total calculations - Other pure business logic

Database

Tables (database/tables/)

SQL table definitions for PostgreSQL:

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

Migrations (database/migrations/)

Database schema migrations:

database/migrations/
├── 001_initial_schema.sql
├── 002_add_stripe_integration.sql
├── 003_add_payment_history.sql
├── 009_create_projects_table.sql
├── 010_create_project_customers.sql
└── ...

Functions (database/functions/)

Database functions and triggers:

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

Infrastructure

Bruno (infra/bruno/)

API testing collection:

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

Gitea (infra/gitea/)

CI/CD configuration:

infra/gitea/
├── compose.yml             # Docker Compose for Gitea
└── runner_config/
    └── config.yaml         # act_runner configuration

Workspace Configuration

pnpm-workspace.yaml

Defines the monorepo structure:

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

Package Dependencies

Packages reference each other using the workspace:* protocol:

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

Documentation

docs/ Directory

Comprehensive documentation organized by type:

  • guides/ - How-to guides (setup, testing, deployment)
  • features/ - Feature documentation
  • architecture/ - Architecture deep dives
  • issues/ - Detailed issue implementation docs

All documentation is cross-linked for easy navigation.

See Also