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
New to the project? → 01-handbook/onboarding.md
Claude Code? → ../CLAUDE.md
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).
| 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, canonical base URL / site address, installation identity, absolute URLs in mails | topics/bootstrap.md |
| cache, DataCache, APCu, page cache | topics/cache.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 |
| 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 |
| 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 |
installer, composer install, project setup |
topics/installer.md |
| jobs, cron, queue, scheduling, background work, z77-run CLI, throttling, long-running tasks | topics/jobs.md |
| login, auth, session, AccessGuard | topics/login.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 |
| routing, router, Request, ControllerHandler | topics/routing.md |
| security, hardening, setup token, password policy | topics/security.md |
| stylesheet, asset pipeline, AssetCleaner | topics/stylesheet.md |
| translation, Translator | topics/translation.md |
| tree, hierarchy | topics/tree.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
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 | 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) |