README

Welcome. This documentation serves two purposes:

Knowledge transfer — Successors and new developers understand the system
Development — New features are planned and implemented in a structured way

Start Here

New to the project? → 01-handbook/onboarding.md

Claude Code? → ../CLAUDE.md

Structure

01-handbook/ — Knowledge Transfer

Everything a new developer needs to understand the system and work with it. Two layers: Reference (understand the system) and the Cookbook (step-by-step recipes — what a project follows when building).

Reference — understand the system

Document	Content
onboarding.md	Day 1: What is this, where is what, how do I start
dev-environment.md	Toolchain setup & verification (PC switch): tools, SSH/gh access, post-sync steps + `verify-dev-env.sh`
architecture.md	How the framework is structured
conventions.md	Coding standards, namespaces, file names
css-conventions.md	CSS/SCSS standards: BEM, tokens, components
templates.md	Template layer: location, context injection, partials
installer.md	Composer installer: configuration, generated files, directory structure
release-structure.md	Zero-downtime deploys on shared hosting: shared/releases/current/next, SSH setup, switch mechanics
vision.md	Why this framework, goals, scope

Cookbook — build recipes (for projects)

Recipe	Content
create-module.md	Step-by-step: Creating a new module
create-page.md	Step-by-step: Creating a new page (routing → action → assets → rendering)
dms-images.md	Image-size profiles config + displaying DMS images (`mediaUrl`/`mediaImage`)
patterns/	Reusable project components (slider, …) + graduation lifecycle

topics/ — Single Source of Truth per Work Area

One file per work area: entry points, file map, mental model, rules, known issues, pendenzen. Read the matching topic doc before writing or analyzing code in that area. Structure is enforced by npm run docs:check (docs-lint/STANDARD.md).

Topic trigger map

You are working on / keywords	Read
alert, alarm, outage notification, operator mail/SMS, escalation, monitoring signal	topics/alert.md
API, /api, module-api, bearer key, tenant key, stateless route, ApiKeyGuard, JSON endpoint, data broker	topics/api.md
backend, dashboard, service panel, user preferences, system pages	topics/backend.md
backup, restore, z77-backup CLI	topics/backup.md
content block types	topics/block-types.md
bootstrap, DI container, debug flag, systemConfig, module config override / config merge, canonical base URL / site address, installation identity, absolute URLs in mails	topics/bootstrap.md
cache, DataCache, APCu, page cache	topics/cache.md
contact / Kontakt, address / Adresse, address type / Adresstyp, ContactAddress, typed addresses, invoice address / delivery address, person / organisation, module-contact	topics/contact.md
content, structured content, content files	topics/content.md
CSS/SCSS backend, werkbank	topics/css-backend.md
CSS/SCSS dms	topics/css-dms.md
CSS/SCSS frontend, public design	topics/css-frontend.md
CSS watch, `npm run watch` / `build`	topics/css-watch.md
debtor / Debitor, receivables / Debitorenbuchhaltung, debtor profile / `DebtorProfile`, payment terms / Zahlungskonditionen / `PaymentTerms`, discount / Skonto, payment target / Zahlungsziel / `PaymentTarget`, IBAN, QR-IBAN, QRR / NON reference, dunning / Mahnung / Mahnstufe / `DunningLevel`, Mahngebühr, Mahnsperre, `debtorAccounts`, Debitoren-Sammelkonto, Rundungsdifferenz Rechnung, `LedgerAccountCheck`, invoice / Rechnung, credit note / Gutschrift, `InvoicingService`, `InvoiceDraft`, `invoicing` / `final`, reinvoice / neu fakturieren, finalize / Fakturierung abschliessen, rounding line / Rundungszeile, address snapshot / `AddressSnapshot`, `AccountingGateway` / accounting port, `NullAccountingGateway`, open amount / offener Betrag, module-debtor	topics/debtor.md
documents, DMS, drive, upload, delivery	topics/documents.md
entities, hydration, entity data handling	topics/entity-data-handling.md
fetch, AJAX, CSRF, form validation	topics/fetch.md
financial / Finanzbuchhaltung, bookkeeping / ledger, account / Konto, chart of accounts / Kontenplan, KMU-Kontenrahmen, account type, fiscal year / Geschäftsjahr, period / Periode, period state, journal / Buchung / journal entry, journal line, posting / `PostingRequest` / `EntryRef`, `LedgerService`, idempotency key, reversal / Storno, manual entry / manuelle Buchung, change log / Änderungsprotokoll (`EntryChange`), number gap, journal-entry range, report / Auswertungen, trial balance / Saldobilanz, balance sheet / Bilanz, income statement / Erfolgsrechnung, account statement / Kontoblatt, `LedgerReports`, module-financial	topics/financial.md
forms, public form / formular, contact form fields, form validation rules, honeypot, blur check	topics/forms.md
i18n, languages, locale switching	topics/i18n.md
import, data adoption, seed records into existing installation, wdv migration, ImportIdentity	topics/import.md
mandator / Mandant, own company / eigene Firma, letterhead / Briefkopf, UID / Unternehmens-Identifikationsnummer, `CHE-`, VAT liability / mehrwertsteuerpflichtig, default tax code / Standard-MWST-Code, account settings / Kontenzuordnung, `vatAccounts` (moved), `debtorAccounts` (moved), `CurrentMandator`, `MandatorAccounts`, `LedgerAccountCheck`, `vatAccountFor`, letterhead vs. payee / Zahlungsempfänger, multi-mandator / Mehrmandant, module-mandator	topics/mandator.md
money, amounts, Rappen, minor units, rounding 0.05, allocate, percentage	topics/money.md
installer, `composer install`, project setup	topics/installer.md
jobs, cron, queue, scheduling, background work, z77-run CLI, throttling, long-running tasks	topics/jobs.md
JavaScript build, minify / minifizieren, `.min.js`, terser, `npm run build:js` / `check:js`, vendor marker `@z77-js`	topics/js-build.md
login, auth, session, AccessGuard	topics/login.md
lottie, animation, `<lottie-figure>`, poster	topics/lottie.md
mail, email, e-mail versand / configure email sending, SMTP, contact form / kontaktformular, form mail, emailConfig, sender / from address, EmailService, backend mail settings	topics/mail.md
member accounts, customer login / kundenlogin, passwordless, magic link, registration / registrierung, TOTP 2FA, stay signed in / angemeldet bleiben, device keys, invitation / einladung, grants, several tenants / mehrere Mandanten, tenant switch / mandantenwechsel	topics/member.md
messages, flash messages	topics/messages.md
metadata, SEO	topics/metadata.md
navigation	topics/navigation.md
packaging, monorepo split, Packagist, release/tagging	topics/packaging.md
persistence design, repositories, drivers	topics/persistence-architecture.md
file driver, JSON storage	topics/persistence-file.md
doctrine driver, MariaDB, database.inc.php, doctrineEntities, doctrineEntitiesConfig, project entity, DECIMAL / money column, charset / collation, z77/persistence-doctrine, transaction / getTransaction / run(), rollback, TransactionRolledBackException, NumberRange / gapless numbering / next(), openWorkChecks / openWorkChecksConfig / open-work check / period-close / stocktake block, NumberRange create()	topics/persistence-doctrine.md
routing, router, Request, ControllerHandler	topics/routing.md
security, hardening, setup token, password policy	topics/security.md
web statistics / Statistik / Besucherzahlen, page views / Seitenaufrufe, visitor key / daily salt, `StatsRecorder`, `stats-rollup`, beacon / event endpoint / `statsEvents`, referrer / Herkunft, `data-stats="off"`, privacy text / Datenschutztext Statistik	topics/stats.md
stylesheet, asset pipeline, AssetCleaner	topics/stylesheet.md
translation, Translator	topics/translation.md
tree, hierarchy	topics/tree.md
VAT, MWST, Mehrwertsteuer, tax code / Steuercode, TaxCode, TaxRate, rate valid from / gültig ab, VatCalculator, tax summary, price mode net / gross, country pack, ESTV, module-vat	topics/vat.md
view layer, partials, HtmlView	topics/view-layer.md
templates (create/change)	01-handbook/templates.md

02-decisions/ — Architecture Decision Records (ADRs)

Why was X built this way and not another? Every important decision has its own document. Prevents successors from reversing decisions that have already been thought through.

03-development/ — Feature Lifecycle

New features from idea to implementation.

Document/Folder	Content
roadmap.md	Milestones and priorities
triage.md	Process: when is what addressed
ideas/	Raw ideas — not yet evaluated
concepts/	Elaborated concepts — under discussion
specs/	Technical specs — approved, ready for implementation

04-changelog/ — Version History

External Packages (z77 vendor, outside this repo)

Vendor/domain integrations are separate repositories — never part of this monorepo (see ADR-027). The Composer vendor z77 is branding, not location. Currently:

Package	Content	License
`z77/propbase`	PropBase (myprop.ch) real-estate API core — framework-agnostic, own repo + docs	proprietary → MIT planned
`z77/module-propbase`	z77 adapter for PropBase (controllers, presenters, templates) — planned	proprietary

Projects consume these via Composer (path repository in development).

Status Conventions

Status	Meaning
`[IDEA]`	Raw idea, not yet evaluated
`[CONCEPT]`	Elaborated, under discussion
`[APPROVED]`	Spec approved, implementation can start
`[IN PROGRESS]`	Currently being implemented
`[DONE]`	Implemented and in production
`[REJECTED]`	Deliberately not pursued further (with reason)

z77 / docs

Package info

Security

Statistics