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, 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

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

Maintainers

Package info

Statistics

Security