Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Projektstruktur & Architektur
Core Domain Models
- Account: Billing entity ABOVE organisations (bundles orgs for billing; tenant-independent, owner ≠ org data access — see
doc/billing_agentur_konto_plan.md) - Organisation: Multi-tenant root entity
- User: Authentication + tenant membership via roles
- Project: Container for work items within organization
- Ticket: Work items with status, assignments, comments
- Document: File management with versions
- TimeSession: Time tracking with project/ticket association
- Notification: Real-time notification system with channels
- Activity: Audit trail for all model changes
Key Architectural Patterns
- Multi-tenancy: Every model scoped to Organisation via acts_as_tenant
- Component-based UI: ViewComponent + Stimulus hybrid architecture
- Activity Tracking: Automatic audit trail via callbacks and observers
- Notification System: Event-driven notifications with fanout service
- Service Objects: Complex business logic encapsulation
- Background Processing: Solid Queue (einziges Job-Backend; Sidekiq ist entfernt)
Build & Test Commands
Runtime: Ruby 4.0.7 (
.ruby-version), Rails 8.1.4.1,config.load_defaults 7.2. CI reads Ruby from.ruby-version.Development server: zwei Prozesse nötig —
bin/dev(Tailwind-Watch + Solid Queue viaProcfile.dev) UNDbin/rails server -b 0.0.0.0.Procfile.deventhält keinenweb:-Eintrag (entfernt in9e4673fc),bin/devallein startet also keine Anwendung.Background jobs: Jobs laufen automatisch mit Solid Queue in Development
Tests ausführen:
- Alle Tests:
rspec - Einzelne Datei:
rspec spec/path/to/file_spec.rb - Einzelner Test:
rspec spec/path/to/file_spec.rb:LINE_NUMBER - Mit Debug-Output:
RAILS_LOG_LEVEL=debug rspec ...
- Alle Tests:
JS-Tests (reine Stimulus-Lib/Parser via Node
node:test, kein Chrome nötig):npm testPython-Tests (
bin/lala, Attrappe des MCP-Endpunkts im selben Prozess, nur Standardbibliothek):python3 -m unittest discover -s spec/python -p '*_test.py'Product screenshots for the project website:
MARKETING_SCREENSHOTS=1 bundle exec rspec spec/marketing/screenshots_spec.rb, output intmp/screenshots/marketing/<locale>/, excluded from every normal run. The README's four pictures are copied from there by hand to.github/readme/; thenbundle exec ruby script/readme_galleryredraws the framed tiles of its gallery.System-/JS-Tests auf einer ARM-Maschine (Parallels-VM):
selenium-webdriverliefert für Linux nur eine x86-64-Binary vonselenium-manager, für macOS dagegen eine Universal-Binary. Auf aarch64 lehnt der Kernel sie ab und/bin/shmeldet stattdessen1: Syntax error: "(" unexpected, ohne die Architektur zu erwähnen. Abhilfe: chromedriver aus der Distribution installieren (sudo apt install chromium-driver) und, falls er nicht unter einem der Standardpfade liegt,CHROMEDRIVER_BIN(und bei BedarfCHROME_BIN) setzen. Besitzer der Auflösung istLocalChromeinspec/support/capybara.rb, Guard:spec/architecture/chrome_driver_binary_guard_spec.rb. Auf dem Mac greift nichts davon, dort bleibt Selenium Manager zuständig.CI:
.github/workflows/guards.ymlruns six jobs on every PR, with no path filter (not on a push to main, and a new push cancels the superseded run; by hand viaworkflow_dispatch, reasons in the workflow header):guards(curated specs plusbrowser_database_cleanup_spec.rb,mobile_ticket_navigation_spec.rb,mobile_assistant_layout_spec.rbandmobile_shell_regressions_spec.rb),javascript(Node unit tests),lala(Python tests ofbin/lala,spec/python/),rubocop,brakemananddependencies. The Rails/browser job needs noRAILS_MASTER_KEY(Rails generates a local test secret); npm lifecycle scripts are disabled withnpm ci --ignore-scripts, and fonts are copied explicitly. Browser fixtures are nontransactional so Puma can read them; failure artifacts includetmp/screenshots/,tmp/capybara/and explicit mobile captures. A red RuboCop run means a new offense against the frozen baseline. A red guards job needs inspection of the failing step, including browser/infrastructure failures. ⚠️ Die kuratierte Liste ist handgepflegt. Wer eine Spec löscht, löscht ihre Zeile dort mit: rspec kann die Datei nicht LADEN und meldet „0 examples, 1 error occurred outside of examples", was nach Infrastruktur aussieht und keine ist. Ein lokaler Lauf der Liste fängt das nicht, wenn man die Pfade vorher auf existierende filtert. Wächter:spec/architecture/ci_guard_list_spec.rb(prüft auch, dass kein.jsan rspec geht, das fährt derjavascript-Job mit Node). ⚠️ Ein Sicherheits-Spec trägt:ci_guardan seinemdescribe(RSpec.describe Foo, :ci_guard, type: :request do, das Tag vor den Keyword-Argumenten). Derselbe Wächter verlangt, dass jede so markierte Datei in der Liste steht, einzeln oder über ein Verzeichnis darüber. Eine gestrichene Zeile wird damit rot statt still. Bis zum 27.09.2026 liefen die Regressions-Specs von #895 und #896 nirgends. Neue Specs zu Rechten, Mandantengrenzen oder behobenen Lücken: Tag setzen und Pfad eintragen. The full suite and fullerblintstill run locally (known drift, separate cleanup).Docker (
Dockerfile,compose.yml,compose.build.yml,.env.docker.example): for self-hosters only, our servers deploy with Capistrano and never run the image. Each published release buildsghcr.io/lalabase/lalabase:<version>for amd64 and arm64 (.github/workflows/docker-release.yml), checks it withscript/docker_checkand only then pushes it.compose.ymlpulls the release in itsimage:line, whichscript/release preparewrites andpublishholds against the version (guard:changelog_guard_spec.rb); never edit that line by hand..github/workflows/docker.ymlbuilds from the checkout (compose.build.yml) and boots the stack, only for PRs touching the image,config/orapp/assets/. Every production setting that names a host goes throughLalabase::InstanceSettings; withoutLALABASE_HOSTit returns our servers' values unchanged (pinned byspec/config/instance_settings_spec.rb). ⚠️ The compiled CSS carries the asset host. The image precompiles withASSET_HOST=set and empty; without it every instance would load its fonts from lalabase.com.Leaks (
.github/workflows/leaks.yml): a workflow of its own on every PR and on every push to main. One job,leaks, over everything the PR makes public, not only its end state: every commit (merges by their diff against main, so a conflict resolution counts), every commit message, who wrote and committed it, every name a commit adds (binaries, links, renames), the PR's branch name, title and body (GitHub writes them into the commit on main), and the files as they end up. gitleaks with.gitleaks.toml(default rules without any upstream exception by path,--redact,--textso a-diffattribute hides nothing), and leak guard (script/leak_guard,Lalabase::LeakGuard): forbidden file types, runtime data, symbolic links, and keyed digests (config/leak_guard.digests, HMAC with the secretLEAK_GUARD_KEY) of what only the maintainers may know. The plain list and the generator live in the private repository; never write one of those words here, not even in a comment. Locally:LEAK_GUARD_KEYin.env, thenscript/leak_guardandscript/leak_guard history origin/main..HEAD. ⚠️ Commits to this repository carry the maintainer's GitHub noreply address (repositoryuser.email). A private address as author is public with every commit, and the guard turns it red: set it in every new clone and on every machine or agent environment that commits. ⚠️ The net comes from the base, not from the PR (script/leak_guard net): a PR that weakens it, say by allowing a real key "to make the CI green", is still checked by the old one, and the job summary names the change. The labelleak-net-changemakes a run use the PR's own net; set it only after reading that part of the diff (a new dummy key in the allowlist needs it). The.gitleaks.tomlcheck ingitleaks_config_problemsis a tripwire, not a proof; do not extend it, the base net is the protection. ⚠️ Green only means checked. Ways it once said green after checking nothing: a wrong key (the digests carry a key check), a base commit missing from the clone (theRangestep stops first), a NUL byte or a marker line that cut the log short, a range without commits. A new way of skipping is a red test first. Not covered, on purpose (accidental leaks are the threat model): a secret in a UTF-16 file (gitleaks does not read it; the guard reads its words), what is pushed without a PR (the pre-push hook on switch day), tags and notes.Zwei Sicherheits-Jobs, absichtlich getrennt. Ein Job trägt genau einen Status, und
dependenciesist heute rot (s. u.). Zusammengelegt wäre brakemans Rot von diesem Rot nicht mehr zu unterscheiden, und brakemans ganzer Wert ist die Aussage „Rot = NEUER Befund":brakeman, gegen die frozenconfig/brakeman.ignore-Baseline (38 Einträge, Stand 20.10.2026; derconstantize-Eintrag im Datei-Proxy ist mit #915 behoben statt neu eingefroren, der Eintrag der Titelsuche ging mit dem Umbau der Ticketsuche). Rot = NEUER Befund. Jeder Eintrag ist geprüft und nennt imnote-Feld den Grund, warum er sicher ist; die Datei darf nur schrumpfen, und ein neuer Eintrag braucht dieselbe Begründung. Ausnahme seit 20.10.2026: das TRUNCATE des Demo-Resets (lib/lalabase/demo/reset.rb), ohne Eingabe; Brakeman sieht die Quotierung durchmapundjoinnicht. Bei der Prüfung am 26.09.2026 war einer eine echte SQL-Injection (Ticketsuche, #889); fünf weitere wurden gehärtet statt eingefroren. ⚠️ Ein eingefrorener Eintrag ist öffentlich sichtbar: „ungeprüft" darin ist eine Liste mit Angriffszielen. Ein früherer hochkonfidenter Eintrag,_filter_pills.html.erb:97(XSS), wurde am 31.08.2026 behoben statt neu eingefroren: eine Zeilenverschiebung änderte seinen Fingerabdruck, und da die Datei nur schrumpfen darf, sind die fünf handgebauten"#{request.path}?#{...}"jetzt ein Erbauer mit benannter Route (TimeSessionsHelper#time_list_filter_url). Genauso am 08.09.2026ad_hoc_filter_service.rb:248(SQLi im Datumsfilter): die Zeile verschob sich, der Fingerabdruck änderte sich, und die Bedingung ist jetzt Arel statt SQL-Stringdependencies(bundler-audit), ohne Ignore-Liste. Ein verwundbares Gem ist keine Drift, sondern eine Versionsnummer; die Antwort ist ein Update, kein Vermerk. Seit dem fünften Schritt der Abhängigkeits-Serie (#640, #641, #649, #657, Rails 8.0.5.1 auf main) ist der Job grün: rot = NEUE Meldung, und die Antwort ist wieder eine Versionsnummer
Code-Qualität:
- Ruby linten:
rubocop - ERB linten:
erblint --lint-all - Security Scanner:
bundle exec brakeman— nichtbin/brakeman: der Shim erzwingt--ensure-latestund bricht mit Exit 5 ab, sobald es upstream eine neuere Version gibt, ohne überhaupt zu scannen - Abhängigkeiten prüfen:
gem install bundler-audit && bundle-audit check --update(bewusst nicht im Gemfile: das Werkzeug prüft dieGemfile.lockund darf nicht von ihr gepinnt werden)
- Ruby linten:
Assets:
- Tailwind-CSS baut
tailwindcss-rails(dev:bin/rails tailwindcss:watchvia Procfile.dev, einmalig:bin/rails tailwindcss:build); die übrigen Stylesheets bündelt Sprockets über die*= require-Direktiven inapplication.css - Bootstrap-Icons-Fonts nach
public/fontskopieren (einmalig nachnpm install):npm run copy:fonts
- Tailwind-CSS baut
Database:
- Migrationen:
bin/rails db:migrate - Schema laden:
bin/rails db:schema:load - Seeds:
bin/rails db:seed(läuft auch automatisch, wenndb:prepareeine Datenbank neu anlegt). Lädt immer die Persona-Stammdaten, in Development zusätzlich eine kleine Demo (db/seeds/demo.rb). Die Seeds löschen nie etwas und enthalten keine echten Adressen, nur@example.com(Guard:spec/architecture/seeds_guard_spec.rb) - Erster Instanz-Admin einer frischen Installation:
bin/rails lalabase:setup(LALABASE_ADMIN_EMAIL/LALABASE_ADMIN_PASSWORDoder Abfrage im Terminal; verweigert, sobald ein Beuser existiert). Der erste Nutzer registriert sich danach unter/users/sign_up
- Migrationen:
Multi-Tenancy & Security
acts_as_tenant Essentials
Kritische Prüfungen:
acts_as_tenantgesetzt?- Default-Scope korrekt?
- Seeds/Factories tenant-aware?
- Queries filtern korrekt auf tenant?
- Optionaler
belongs_toauf ein mandantenfähiges Modell steht VORacts_as_tenant(oder hat eine eigene Validierung). acts_as_tenant 1.0.1 prüft Fremd-IDs nur für Verweise, die vor dem Aufruf deklariert sind. Pflicht-Verweise schützt Rails selbst, weil der Lesezugriff durch den Mandanten-Scope läuft.SmartFolder.projectstand dahinter und nahm bis zum 16.09.2026 das Projekt einer fremden Organisation an (Guard:smart_folders_tenant_boundary_spec.rb). - Eine rohe
*_idaus Params wird über eine mandanten- oder policy-gebundene Abfrage aufgelöst, nie direkt zugewiesen. Ein Wechsel des Projekts prüft die Rechte im Zielprojekt (Vorbild:TimeSessionsController#move_to_requested_project).
Private Kommentare: eine Regel, kein nacktes ticket.posts
Verbindlich (Guard-Spec: spec/architecture/post_visibility_guard_spec.rb; läuft über den
Verzeichnis-Eintrag spec/architecture/ in der CI-Guard-Liste):
Einen privaten Kommentar lesen sein Adressat, sein Autor und die Kontoadmins. Das entscheidet
nur Post.readable_by(user, organisation) (bzw. #readable_by?, PostPolicy fragt es).
| Wer liest das Ergebnis? | Dann |
|---|---|
| eine Person (Zeitleiste, Suche, Mail an sie, API, MCP) | ticket.posts.readable_by(user, organisation) |
| alle Leser des Tickets (Aktivitäts-Auszug, Zusammenfassung, KI-Antwort) | ticket.posts.public_posts |
- Der Wächter lehnt in Controllern, Services, Queries, Mailern, Komponenten, Views, Presentern,
Jobs und Helpern jedes
.postsohne eine dieser Fortsetzungen ab (erlaubt sind nochfind,build,create!), dazuassociation(:posts)und einJOIN postsohneposts.id IN (. Die Ausnahmeliste darf nur schrumpfen, jeder Eintrag nennt seinen Grund. - ⚠️ Kein Vorladen von
postsfür eine Anzeige. Eine vorgeladene Assoziation enthält alle Posts. Die Zeitleiste hat bis zum 27.09.2026 genau so jeden privaten Kommentar gezeigt. - Bis zum Audit vom 26.09.2026 stand die Regel nur in
PostPolicy. Fünf Leser hatten sie vergessen, zwei weitere fanden sich beim Beheben.
A meeting write locks through Meeting#lock_in_project!
Binding (guard spec: spec/architecture/meeting_lock_guard_spec.rb; runs through the
directory entry spec/architecture/ in the CI guard list):
A meeting can move into another project (Actors::MoveMeeting, under the meeting's row lock).
A write that was authorized against a project takes the same lock through
meeting.lock_in_project!(authorized_project_id) and treats false as "the meeting is gone
from this project": refuse, or answer as if it were not found.
- The guard refuses a bare lock on a meeting (
@meeting.lock!,Meeting.lock,project.meetings.lock) anywhere outsideapp/models/meeting.rb. Its allow list names two actors that lock and then authorize again, under the lock, in the project the meeting is in now (AcceptTicketSuggestion,StartTicketSuggestionRun). It only shrinks, and every entry gives its reason. - In a controller the lock is
with_meeting_in_project { ... }(MeetingInProject): the block runs under the lock, a moved meeting answers 404. The guard asks every write action (each route but GET) ofMeetingsController,MeetingTicketLinksController,MeetingParticipantLinksControllerandMeetingTermCorrectionsController(K4b) for that call or for an actor that locks itself (LOCKING_ACTORS). A check per file had passedcreate_summary, unlocked next to a delete that locked, until a fourth review round. The exception list (NO_MEETING_YET, a write before any meeting exists) only shrinks. WRITERSpins the services that lock: the move, the edit, the analysis publication, the booking, the participant link, the term correction (K4b), and the controller helper. Four review rounds of the move found each of these writes landing in the old project after a move.- ⚠️ Not seen: a write in a service or controller the guard does not name. Writing a
meeting's data (its project, links, analyses, bookings) elsewhere means calling the helper
and adding the file to
WRITERSorCONTROLLERS. - Lock order: the meeting before a booking, an analysis or a glossary term, never the other way round.
ViewComponent & Design System
Komponenten-Entwicklung Patterns
- Naming:
Neo[Name]Componentfür Komponenten, Buttons unterNeo::Buttons::Namespace (z.B.Neo::Buttons::ButtonComponent) - Stimulus Controller:
neo_[name]_controller.js(z.B.neo_button_controller.js) - Hybrid-Ansatz: Struktur/Styling in ViewComponent, Interaktivität in Stimulus
Neo Brutalist Design Language
- Stil: Border-2 black, box-shadow hover effects, bold typography
- Components verfügbar: Button, Card, Tag, Flash, Modal, Forms
- Style Guide: Entwicklung unter
/style-guide, Dokumentationdocs/design/grundlegendes.md
Icons: one set, Bootstrap Icons
Binding (guard spec: spec/architecture/one_icon_set_guard_spec.rb; runs through the
directory entry spec/architecture/ in the CI guard list, no allowlist):
| What | How |
|---|---|
| an icon | <i class="bi bi-..." aria-hidden="true"></i> |
| a drawing of our own (the plus of the main action, the deadline flag, the view switch, a chevron) | an inline SVG of straight strokes and basic shapes |
- No template, component, helper, script or stylesheet carries an icon pasted from another set. Until 2026-09-30 six files carried nine of them (Heroicons, Lucide, the spinner from the Tailwind documentation). Each is somebody's work under its own license, and a pasted path is not a file the license guard can see.
- The guard is a tripwire, not a proof. It takes a path with arcs or Béziers for a pasted icon, because what we draw ourselves has none, and it knows the classes of other icon fonts. ⚠️ It does NOT see a pasted icon of straight strokes only (a cross, a check mark, a menu), a path held in a constant, an SVG file or a sprite. Those are for the person who reads the diff.
- A drawing of our own that really needs a curve (a chart, a gauge) computes its path from numbers in code. A curve written out as a literal is what a pasted icon looks like.
- A state with two signs (pinned or not) puts both icons in the markup and lets the
attribute pick one in CSS (
column_picker.css,aria-pressed). The script flips the attribute and repaints nothing. - The spinner of a button is a ring drawn with a border, in the button's own colour
(
Neo::Buttons::Base#render_spinner). - ⚠️ An icon that is told to turn names its own box:
bi bi-arrow-repeat inline-block animate-spin. An<i>is an inline box, and a transform does not apply to one. It turns only while its parent happens to be a flex or grid container. Two waiting signs stood still that way until 2026-09-30 (ticket header, admin mail log); four others turned by the luck of their parent. The guard reads class lists in templates and scripts; a list put together in Ruby (NeoInfoTagComponent) is held by its component spec. - The cross of a removable tag says what it removes (
components.neo_tag.remove, "%{name} entfernen"): a row of chips is a row of buttons.
CSS-Konvention: KEINE <style>-Blöcke in Views
Verbindlich (Guard-Spec: spec/views/no_style_blocks_guard_spec.rb schlägt sonst fehl):
- CSS gehört in
app/assets/stylesheets/*, niemals als<style>-Block in eine View:layout.css→ globales Spalten-/Layout-System, Listen-/Karten-Interaktionenviews.css→ seitenspezifische Regeln (gescoped auf Seiten-Anker, thematisch gruppiert)components/rich_text_embeds.css→ Rich-Text-Anzeige (Zoom-Link, Lightbox, Platzhalter); Editor und Inhalt stylt Lexxys eigenes Stylesheet (lexxy-content)components/*.css→ gekapselte Komponenten (Vorbild:components/custom_select.css)style_guide.css→ lädt nur im Style-Guide-Layout
- Einzige Ausnahme: Mailer-Layouts (
layouts/mailer.html.erb,layouts/notification_mailer.html.erb) — E-Mail-Clients laden keine externen Stylesheets (Allowlist im Guard-Spec). @applyfunktioniert NUR inapplication.tailwind.css(Build-Zeit). In Runtime-CSS oder<style>-Blöcken ist@applywirkungslos und damit toter Code.- Generische Klassennamen (z. B. SortableJS
.sortable-ghost) beim Zentralisieren auf einen Seiten-Anker scopen, sonst kollidieren Seiten-Varianten.
Frontend: the application loads nothing from a foreign host
Binding (guard spec: spec/architecture/no_runtime_cdn_guard_spec.rb; runs through the
directory entry spec/architecture/ in the CI guard list):
The scripts, stylesheets and fonts of the application, and the markup of its own templates,
are served by the instance. A new frontend dependency is vendored (vendor/javascript,
vendor/assets, with a notice in THIRD_PARTY_NOTICES.txt) or comes from a gem.
The guard asks three questions:
| Question | Where |
|---|---|
| Does a tag, a stylesheet, an import or a request in a script name a foreign address as a literal? | our own files and the vendored ones |
| Does a file carry the address of a public CDN at all? | the same files |
| Both again | the scripts and stylesheets that gems put into the page (Turbo, Stimulus, Action Text, Lexxy), found through the importmap and the stylesheet bundle |
- ⚠️ A vendored file is not a local file. Until 2026-09-30 the Markdown editor of the old
note form sat in
vendor/assetsand fetched a spelling dictionary from jsDelivr and an icon font from BootstrapCDN on every full load of that page: both addresses were strings inside its minified file, both features on by default. Read a new library for addresses before it goes in. The guard reads it again, and reads the gems' files after every update. - ⚠️ The content security policy stops none of this. It runs in report-only mode
(
config/initializers/content_security_policy.rb): it logs a violation and lets the request through. Do not count on it until that line saysfalse. - Synced documentation pages load nothing from elsewhere either, since 2026-11-01.
The sync copies the images a page shows out of the clone (
Documentation::AssetCollector) and the file proxy serves them behind the right of the documentation; an image that is not served shows as its alt text, one with a foreign address becomes a link. Until then every reader of such a page contacted raw.githubusercontent.com. Held bydocumentation_sync_job_spec("names no repository host and no address outside the instance"). - ⚠️ Other content is not covered by this guard, and
img-srcstill allows any https. - Not seen either: an address built at run time (a host in a constant, an interpolated string).
- One named exception,
SAMPLES: the code samples of the style guide are printed as text, and one of them shows the forbidden thing on purpose. A comment that quotes a foreign tag or address trips the guard like the real thing: describe it in words. - The list of public CDNs is incomplete by nature. It is there for the case the first question cannot see.
View-Konvention: KEINE rails-ujs-Optionen
Verbindlich (Guard-Spec: spec/views/no_rails_ujs_options_guard_spec.rb, in der CI-Guard-Liste):
rails-ujs ist in dieser App nicht geladen (config/importmap.rb: „Not used with Turbo").
Zwei verbreitete Rails-Idiome sind damit stiller toter Code — sie werfen keinen Fehler,
sie tun einfach nichts:
| ❌ rails-ujs (wirkungslos) | ✅ Turbo | Symptom ohne Fix |
|---|---|---|
link_to path, method: :delete |
link_to path, data: { turbo_method: :delete } |
Link feuert ein GET → RoutingError bei POST/PATCH-only-Routen, oder stille Navigation, wenn die Route auch GET beantwortet |
data: { confirm: "..." } |
data: { turbo_confirm: "..." } |
Der Bestätigungsdialog erscheint nie, destruktive Aktionen feuern beim ersten Klick |
- Bei
Neo::Buttons::*-Komponenten stattdessen den Top-Level-Kwargconfirm:nutzen — die Komponente mappt ihn selbst korrekt aufturbo_confirm. button_todarfmethod:verwenden: dort ist es die dokumentierte Rails-API und rendert ein echtes Formular. Nur beilink_toistmethod:die Falle.- Der Guard hat keine Allowlist — er startet bei null. Neue Ausnahme heißt: Eintrag anlegen und begründen, warum UJS-Semantik in einer App ohne UJS nötig ist.
View-Konvention: Seitenbreite nur über die Klasse
Verbindlich (Guard-Spec: spec/architecture/page_width_guard_spec.rb; läuft über den
Verzeichnis-Eintrag spec/architecture/ automatisch in der CI-Guard-Liste):
Welche Breite eine Seite bekommt, entscheidet eine Frage: vergleicht man senkrecht Spalten, oder
liest man waagerecht Zeilen? (Abschnitt „Breiten“ in doc/belegungstabelle_oberflaeche.md)
| Klasse | Wann | Im Code |
|---|---|---|
| Voll | Tabelle, Kanban, Matrix: man vergleicht Spalten | kein Deckel |
| Geteilt | Liste und Bahn nebeneinander | kein Deckel; eine offene Bahn hebt jeden Deckel auf |
| Gedeckelt | pro Zeile ein Gegenstand mit einem Wert | .width-capped (620 px), mit Zeichen- oder Zeitspalte .width-capped--wide (820 px) |
- Fließtext in jeder Klasse:
.width-text(70ch). - Die Werte stehen einmal in
layout.css(--width-capped,--width-capped-wide,--width-text). Eine View nennt die Klasse, nie ein eigenesmax-w-*; neues CSS liest die Variable und gibt derselben Zahl keinen zweiten Namen. - Der Deckel sitzt am Inhaltsblock, nie an der Schale, und ist nie zentriert: gedeckelt heißt „endet früher“, nicht „beginnt woanders“. Der Seitenkopf (Titel, Reiter, Titelaktion) bleibt volle Breite.
- Die Altlasten stehen im Guard auf einer Liste, die nur schrumpfen darf: eine umgestellte Seite senkt ihren Eintrag, ein zu hoher Eintrag schlägt ebenfalls an.
View-Konvention: die Seiten ohne Anmeldung teilen EIN Gerüst
Verbindlich (Guard-Spec: spec/requests/auth_pages_skeleton_spec.rb; steht mit eigenem
Eintrag in der CI-Guard-Liste, spec/requests/ ist dort kein Verzeichnis-Eintrag):
Sieben Seiten sieht ein Besucher, bevor er angemeldet ist: Anmeldung, Registrierung,
Registrierung gesperrt, Passwort vergessen, neues Passwort, Bestätigung erneut, Entsperren.
Sie teilen ein Gerüst, und das Gerüst gehört dem Layout application_auth, nicht der View.
Eine View liefert vier Dinge:
| Schlitz | Inhalt |
|---|---|
yield |
Formularspalte: Vorzeile, Überschrift, Formular |
content_for :auth_cross |
der Link oben rechts |
content_for :auth_panel |
der Inhalt des dunklen Panels |
content_for :auth_panel_decorative |
gesetzt, wenn das Panel ein Schaubild ist |
- Der Guard hat keine Ausnahmeliste: keine View unter
app/views/devise/enthältlp-auth-form-col,lp-auth-legaloder ein<aside>. Bis zum 20.09.2026 war das Gerüst dreimal von Hand abgeschrieben, und die vier fehlenden Seiten hätten sieben daraus gemacht. application_sessionlessist NICHT dasselbe Layout. Es behält die Admin-Anmeldung (eigener Styleguide) und die Rechtsseiten einer Instanz und lädtauth.cssnicht.- Passwortfelder rendert immer
devise/shared/_password_field(Augen-Umschalter, optional Stärkeanzeige). Die Beschriftungen stehen unterviews.devise.shared.password_field, nicht je Seite. - Eine neue Seite braucht einen Controller-Eintrag in
devise_forundlayout 'application_auth'. Ohne dendevise_for-Eintrag läuft Devise's eigener Controller mit dem Standard-Layout und rendert die Anwendungshülle für jemanden ohne Sitzung. Genau so stand/users/unlock/newda, seit:lockablescharf ist.
⚠️ Eine Frist im Panel kommt aus der Konfiguration, nie aus dem Text. „Der Link gilt
6 Stunden" liest Devise.reset_password_within, „nach 5 Fehlversuchen" liest
Devise.maximum_attempts. Ein getippter Wert überlebt die geänderte Einstellung und belügt den
Leser; der Guard ändert die Einstellung und holt die Seite noch einmal. Ein Satz, der nur für
bestimmte Einstellungen gilt (Selbstentsperrung nur bei unlock_strategy :time/:both),
steht hinter der passenden Bedingung.
⚠️ Keine Sackgassen. Jede Seite ohne Anmeldung ist von der Anmeldeseite aus anklickbar.
Bis zum 20.09.2026 verlinkte nur devise/shared/_links auf Bestätigung und Entsperrung, und
gerendert hat dieses Partial nichts: beide Seiten waren nur über die Adresszeile
erreichbar, während die Hilfeseite den Link „auf der Anmeldeseite" versprach. Der Guard folgt
dem Link und prüft die Zielseite.
⚠️ aria-hidden nur auf einem Schaubild. Das Panel der Anmeldung zeigt erfundene
Inbox-Zeilen und bleibt versteckt. Ein Panel mit der einzigen Fassung einer Tatsache muss
lesbar sein. Und auf dem Handy blendet auth.css den letzten Schritt einer Schrittliste aus
(.lp-auth-step:last-child) — dort darf keine Tatsache allein stehen, und eine Überschrift
darf die Schritte nicht zählen.
Beispiel-Implementation
<%= render Neo::Buttons::ButtonComponent.new(
variant: :primary,
size: :medium,
icon: "plus-lg",
interactive: true,
form: { action: path, method: :post }
) do %>
Button Text
<% end %>
// app/javascript/controllers/neo_button_controller.js
export default class extends Controller {
static values = { confirm: String }
handleClick(event) {
if (this.confirmValue && !confirm(this.confirmValue)) {
event.preventDefault()
}
}
}
Notification System Architecture
Event-Driven Pattern
- OutboxEvent: Captures model changes via callbacks
- FanoutService: Determines notification recipients
- ScoreCalculator: Calculates notification priority
- Notification: Final notification with channels (in_app, email, webhook)
Zentrales Constants System
# app/models/concerns/notifications/constants.rb
module Notifications::Constants
EVENT_TYPE_TICKET_ASSIGNED = 'ticket_assigned'.freeze
EVENT_TYPE_MAPPING = {
'ticket.assigned' => EVENT_TYPE_TICKET_ASSIGNED
}.freeze
end
Thread-Safety: Verwende vollqualifizierte Namespaces in Background Jobs
# ✅ Richtig in Jobs/Services
event_type = Notifications::Constants::EVENT_TYPE_MAPPING[key]
Critical Bug Fixes (NICHT ÜBERSCHREIBEN!)
Turbo URL-Objekt Bug (12.08.2025)
Problem: Paginierung funktionierte nicht von Detail-Ansichten, generierte /tickets/undefined URLs.
Fix: Zeile ~211 in application.js:
// ✅ RICHTIG - Turbo erwartet URL-Objekt
event.detail.url = currentUrl;
// ❌ FALSCH - würde Bug verursachen!
// event.detail.url = currentUrl.toString();
Wichtig: Diese Zeile NIEMALS auf .toString() ändern! Turbo's interne Verarbeitung erwartet ein URL-Objekt.
Stimulus Controller Index Bug (20.08.2025)
Problem: JavaScript Stimulus Controller 404-Fehler auf Production/Staging durch relative Imports.
KRITISCHE REGEL: Die Datei app/javascript/controllers/index.js verwendet eine custom Implementierung mit eagerLoadControllersFrom.
NIEMALS:
- Die Datei mit expliziten Controller-Imports überschreiben
rails stimulus:manifest:updatedirekt ausführen (zerstört custom Version)- Zurück zu relativen Imports (
from "./controller") gehen
IMMER:
- Die custom
eagerLoadControllersFrom-Lösung beibehalten - Bei Updates
rails stimulus:manifest:update_safeverwenden - Dokumentation in
docs/STIMULUS_CONTROLLER_MANAGEMENT.mdbeachten
Warum: Relative Imports umgehen Importmap-Resolution → ungehashte URLs → 404-Fehler in Production.
Signierte Active-Storage-Adressen in Listen (08.09.2026)
Problem: Die Ticketliste antwortete auf Production manchmal mit 429 „Zu viele Anfragen".
Jede Avatar-Kachel lud ihr Bild über rails_storage_proxy_path, und die Route stempelt den
Ablauf (config.active_storage.urls_expire_in, 15 Minuten) millisekundengenau in die Signatur.
Dasselbe Bild war damit in jeder Zeile eine andere Adresse: kein Browser-Cache, 53 bis 59
Rails-Requests je Listenaufruf, und Rack::Attack (requests/ip, 300 je 5 Minuten,
/rails/active_storage zählt mit) drosselte die Liste selbst.
Fix: Neo::Users::AvatarComponent#picture_url_expires_at rundet den Ablauf auf Slots der
konfigurierten Länge und übergibt ihn als expires_at:; der Link gilt bis zum Ende des
übernächsten Slots. Guards: spec/components/neo/users/avatar_component_spec.rb (Slot-Regel)
und spec/requests/organisations/tickets_name_display_spec.rb (vier Zeilen, eine Adresse).
Hergang: docs/letzte_arbeiten/2026_09_08_1_letzte_arbeiten_avatar_adresse_slot.md.
Wichtig:
- Wer ein Bild je Zeile über eine signierte Adresse rendert (
rails_storage_proxy_path,rails_blob_path,url_for(variant)), bekommt ohne gerundetesexpires_at:denselben Fehler. Die Adresse stabil machen, nicht die Drossel lockern. freeze_timemacht diesen Fehler in einer Spec unsichtbar: alle Zeilen rendern dann zur selben Millisekunde und auch der alte Code liefert eine Adresse. Solche Guards laufen in Echtzeit.
Database Schema & Migrations
UUID Primary Keys
Alle Tabellen verwenden UUID als Primary Key mit gen_random_uuid() default.
PostgreSQL Enums
-- Beispiel für Event Types
CREATE TYPE notification_event_type AS ENUM (
'ticket_commented', 'ticket_assigned', 'ticket_unassigned',
'ticket_status_changed', 'ticket_blocker', 'project_announcement',
'document_added', 'mention', 'system_message'
);
Migration Best Practices
- Migrationen mit
ActiveRecord::Migration[8.1]erstellen - Enum-Erweiterungen:
ALTER TYPE ... ADD VALUE IF NOT EXISTS - Reversible Migrationen schreiben
- Lange Locks vermeiden (add_column ohne Default, dann UPDATE separat)
- Datenmigrationen als Task/Service, NICHT in Schema-Migration
Background Jobs & Performance
Solid Queue (Rails 8 Native)
Haupt-Job-System für Notifications, E-Mails, Cleanup-Tasks.
# Job-Definition
class ProcessNotificationJob < ApplicationJob
queue_as :notifications
def perform(notification)
# Job-Logik
end
end
Performance-kritische Scopes
# app/models/notification.rb
scope :for_notification_center, -> {
includes(:actor, :notifiable, :project)
}
scope :with_email_log_counts, -> {
left_joins(:email_logs)
.group('notifications.id')
.select('notifications.*, COUNT(email_logs.id) as email_logs_count')
}
Caching Strategy
- Fragment Caching für Komponenten:
cache [@notification, 'card_v2'] - Russian Doll Caching für verschachtelte Strukturen
- Database-Level Indizierung für häufige Queries
Testing Strategy
Test-Pyramide
- System-Tests (Capybara): Haupte User-Flows
- Request-Tests: Authentication, Authorization, API-Endpunkte
- Model-Tests: Validations, Scopes, Callbacks, Business Logic
- Component-Tests: ViewComponent isoliert testen
- JS-Tests: Stimulus Controller (wenn komplexe Logik)
Bugfix-Regel
IMMER: Erst reproduzierenden, fehlschlagenden Test schreiben → dann fixen → Test bleibt als Regression Guard.
# spec/models/notification_spec.rb
it 'prevents duplicate notifications for ticket creation with assignees' do
ticket = create(:ticket, assignees: [user])
activity = create(:activity, trackable: ticket, key: 'ticket.created')
expect {
Notifications::FanoutService.new(activity).call
}.not_to change(Notification, :count)
end
Test-Konvention: Statussymbole gehen ungeschützt an Rack
Verbindlich (Guard-Spec: spec/architecture/rack_status_symbol_guard_spec.rb; läuft über den
Verzeichnis-Eintrag spec/architecture/ automatisch in der CI-Guard-Liste, ohne eigenen Eintrag):
Rack 3.1 hat zwei Statussymbole umbenannt, Rack 3.2 warnt bei jedem Aufruf der alten Schreibweise und kündigt ihre Entfernung an. Der Zahlenwert bleibt in beiden Fällen gleich.
| ❌ veraltet | ✅ aktuell | Code |
|---|---|---|
:unprocessable_entity |
:unprocessable_content |
422 |
:payload_too_large |
:content_too_large |
413 |
- Im Controller ist die alte Schreibweise harmlos, aber erst ab actionpack 8.0.5.1:
ActionDispatch::Response.rack_status_codeübersetzt in beide Richtungen, bevor Rack gefragt wird. Unter 8.0.2 gibt es diese Schicht noch nicht, dort warnt auchrender status:. Rails und Rack müssen deshalb zusammen wandern. - In Specs gibt es die Schicht nie. rspec-rails reicht das Symbol unverändert an
Rack::Utils.status_codeweiter (have_http_status.rb:219). Genau darum deckt der Guardspec/ab und nichtapp/. - Der Guard prüft gegen
Rack::Utils::SYMBOL_TO_STATUS_CODEstatt gegen eine Wortliste: was dort fehlt, ist veraltet. Die nächste Umbenennung fängt er ohne Pflege mit ab.
Factory Patterns
# spec/factories/notifications.rb
FactoryBot.define do
factory :notification do
association :recipient, factory: :user
association :organisation
event_type { Notifications::Constants::EVENT_TYPE_TICKET_ASSIGNED }
channel { 'in_app' }
# tenant-aware factory
end
end
Verzeichnis-Karten (nested CLAUDE.md)
Für die teuersten Bereiche existieren verzeichnis-lokale Karten, die Claude Code automatisch
lädt, sobald dort gearbeitet wird: app/models/, app/services/ (+ notifications/,
lalabase/), app/controllers/concerns/, app/javascript/controllers/. Karten sind ≤ ~40 Zeilen,
tragen ein Stand-Datum und verweisen statt zu duplizieren.
Boy-Scout-Regeln (bei ohnehin anstehender Berührung, kein Big Bang)
- Flaches Modell einer Namespace-Domäne substanziell angefasst → in den Namespace ziehen (
self.table_namebehalten). - Nicht-trivialer Controller-Write angefasst → Actor extrahieren (Seam-Regel oben).
- Service ohne
.call(**kwargs)-Konvention substanziell geändert → migrieren + von der Guard-Allowlist streichen. - Inline-
<script>-Heredocs in Controller-Actions angefasst → in Turbo-Stream-Templates/Stimulus verlagern. - Duplikat-Stimulus-Controller berührt → auf die
neo_*-Variante konsolidieren (Liste:app/javascript/controllers/CLAUDE.md).
Pattern-Auswahl Quick Reference
- ViewComponent: Wiederverwendbare UI-Komponenten mit Kapselung, Testbarkeit
- Service Object: Komplexe Business-Logik, mehrere Schritte, externe APIs
- Concern: Kleine, wiederverwendbare Logik über mehrere Modelle/Controller
- Job (Solid Queue): >200 ms, externe Requests, Batch/Retry nötig
- Turbo Stream: Kleines, lokales UI-Update, serverseitig getriggert
- Stimulus Controller: Komplexere Client-Interaktionen oder State im Browser
- Feature Flag: Riskante Änderungen, inkrementelles Rollout
- Form Object / View Model: Komplexe Formulare, mehrere Modelle
Actor-Pattern (Write-Seam)
Nicht-triviale Schreibvorgänge laufen über Command-Objekte unter app/services/actors/
(Actors::SaveTicket, Actors::DestroyPost, …). Ein Actor kapselt einen Write: Transaktion,
Validierungs-/Fehler-Mapping, Current.user fürs Activity-Tracking, Side-Effect-Jobs nach Commit.
Gehärtet in Actors::BaseActor; der Vertrag wird per Guard-Spec
(spec/services/actors/actor_contract_guard_spec.rb) erzwungen.
Naming (Kollision auflösen)
„Actor" meint hier ein Command-Objekt. Es hat nichts mit Activity#actor /
Notification#actor zu tun — die bezeichnen den Audit-User, der eine Änderung ausgelöst hat.
Bewusst disjunkt; nicht vermischen.
Seam-Regel: wann Actor, wann Controller?
- Nicht-trivialer Write → Actor. Nicht-trivial = Multi-Step / eigene Transaktion / Activity-Tracking / Fanout / Background-Job / externer API-Call / Assoziations-Sync.
- Trivialer Write → Controller. Trivial = einzelnes
update!/create!auf einem Model ohne Side-Effects. Triviales CRUD bleibt im Controller (kein Blanket-Rollout).
Vertrag (verbindlich, Guard-geprüft)
- Keyword-Args überall:
Actors::X.new(project:, params:, id: nil, current_user:). Der User-Parameter heißtcurrent_user:(NICHTactor:— Kollision, s. Naming). - Einstieg bevorzugt
Actors::X.call(...);.new(...).callnur, wenn der Aufrufer#recordvor#callbraucht (z. B.PostUpdateService). - Tier 1 (Standardfall): nur
#perform(+#record, optional#enqueue_jobs) implementieren —BaseActor#callübernimmt Transaktion, Fehler-Mapping,Current.user, Enqueue. - Tier 2 (Ausnahme, in der Guard-Allowlist
tier_2_actorsim Guard-Spec): eigener#call, teilt nur die Helper. Die maßgebliche Liste ist die Allowlist selbst (aktuell 5:SaveTicket,AcceptTicketSuggestion,CreateAiPost,GenerateGroupCustomerDescriptions,CreateSignup;MoveTicketist seit 08.09.2026 Tier 1, sein Nummern-Retry lebt inTickets::Mover) — Begründungen je Actor stehen als Kommentar amtier_2_actors-Let im Guard-Spec. - Fehler: Domänen-Fehlschläge per
raise Actors::ActorError, msg(→ failure-Result);RecordInvalidwird automatisch gemappt. Alles andere ist „unerwartet" →handle_unexpected_error: dev/test re-raise (laut crashen), production loggen + failure. - Jobs: NIE rohes
perform_later— immerenqueue_after_commit { SomeJob.perform_later(...) }, damit der Job erst nach dem äußersten echten Commit feuert (korrekt bei Verschachtelung). Current.user: NIE selbst setzen —with_actor_contextsetzt + stellt wieder her (kein Leak).#record: liefert den primären Datensatz odernil(nie eine Collection).
Service-Konvention (app/services)
Neue Services: Entry-Point ist Klass.call(**kwargs), #initialize nur Keyword-Args, mindestens
eine erklärende Kommentarzeile am Dateikopf. Read-/Query-Objekte mit Domänen-Verben deklarieren
stattdessen # Entry point: <methode> im Header. Erzwungen durch
spec/services/service_convention_guard_spec.rb (Bestand auf shrink-only-Legacy-Allowlist —
bei substanzieller Änderung migrieren + streichen). Details: app/services/CLAUDE.md.
API-Namensräume (Kern gegen getrennte Website)
Drei Namensräume unter /api, und sie unterscheiden sich darin, wer ruft:
| Namensraum | Aufrufer | Ausweis | Vertrag |
|---|---|---|---|
Api::V1::*, Api::McpController |
ein Mensch mit Konto | persönliches Zugangstoken + Pundit | doc/mcp_server_plan.md |
Api::Public::* |
jeder, auch niemand | keiner, nur lesend | docs/api/public_v1.md |
Api::Provisioning::* |
die getrennte Website | ein geteiltes Geheimnis aus ENV | docs/api/provisioning_v1.md |
- Beide neuen Namensräume erben von einer eigenen
ActionController::API-Basis, nie vonApplicationController: keine Session, kein Pundit, kein Mandant aus der Sitzung. Wächter:spec/architecture/{public,provisioning}_api_contract_guard_spec.rbprüfen die Klassen, nicht den Text. - Die Provisioning-Tür ist aus, wenn kein Geheimnis gesetzt ist (404, nicht 403): eine fremde Instanz trägt keine Tür, die sie nicht benutzt. Ein persönliches Zugangstoken wird dort nie akzeptiert, es gehört zu einem Menschen mit Organisationen.
- Der Schreibvorgang selbst gehört dem Actor, den auch das Formular im Kern nutzt
(
Actors::CreateSignup). Eine zweite Registrierungslogik neben ihm ist der Fehler, den W2 gerade beseitigt hat. - Zwei Formulare, ein Schreibvorgang. Unser Registrierungsformular lebt in
gboyke/lalabase-websiteund darf aussehen, wie wir wollen; das Formular im Kern gehört den Instanzen, die ihn selbst betreiben, und den Eingeladenen (ein Einladungstoken kann eine fremde Anmeldeseite nicht einlösen). Getrennt sind die Formulare, nie der Actor. Was nur unserem Geschäft gehört, steht deshalb im Website-Formular: der Neugründer-Rabatt ist am 20.09.2026 aus dem Kern-Formular verschwunden,FounderSignupund die Provisioning-Tür bleiben. - Antworten tragen eine Hülle:
data.<ding>im Erfolg,error.{code,messages}im Fehler.codeist maschinenlesbar,messagessind übersetzter Text.
For the REST ticket member routes (including GET /tickets/:ticket_id/posts/:id) and the
number route, Api::V1::ReadableTicket resolves tickets
through the token's effective organisation/project reach and TicketPolicy::Scope:
missing and unreadable tickets return 404 with {"error":"not_found","code":"not_found"}.
Denied actions on readable tickets remain 403; read-only tokens reject writes with 403
("code":"read_only") before any ticket lookup, including missing IDs. Status and body are equal for missing and
unreadable tickets, but queries are not: discovering the unknown tenant reads only
organisation_id and project_id first. Ticket IDs are random UUIDs, not sequential
numbers; this deliberately accepts query asymmetry instead of searching every
organisation the token reaches. It makes no constant-time guarantee.
What a token holder can find is decided by Tickets::ReadableForToken alone (REST, MCP tools,
Tickets::RelationAccess), reach before policy scope. token: is required on it and on
Tickets::RelationAccess: nil means no second limit and is written out by the callers without
a token. Guards: spec/architecture/ticket_token_lookup_guard_spec.rb (also refuses these
finders and TicketRelation.visible_to without a token on the token surfaces) and
ticket_relation_actor_callers_guard_spec.rb.
/api/v1 for programs (REST R0, 2026-10-28; the terminal client moves from MCP to REST
feature by feature):
- Error bodies keep
errorand the HTTP status as they always were and addcode, the MCP vocabulary (invalid_input,read_only,forbidden,not_found,refused, plusunauthorized); an unmapped actor code isrefusedwith the old value asreason. One status changed on purpose: an unexpected actor failure (internal_error) ontime_sessions.create(R6) andposts.create(R3a) answers 500 without the exception's text, where it was a 422 that carried it. Every body comes fromApi::V1::ErrorBodythroughBaseController#render_error; guardspec/architecture/api_v1_error_body_guard_spec.rb. Answers outside the controllers carry nocode: the Rack::Attack 429 (plain text), a 500 from the exceptions app, a 400 for a query string Rack cannot decode (?x=%; raised in middleware before any controller), a query or path parameter of raw bytes that are no valid UTF-8 (?q=%FF, an HTML 400 before authentication, the same whatever exists), and a 400 for a body parameter of raw bytes that are no valid UTF-8, form or JSON (Rails raisesActionController::BadRequestwhen it first reads the parameters, in its params wrapper or its request log, before any callback orrescue_fromofBaseControllerruns; a JSON escape of a lone surrogate is a parse error instead, answered as 400bad_requestwithcode). The 401 of/api/mcp(same concern,render_unauthorized) keeps its old body. Idempotency-Keyon every write (idempotent :createin the controller,Api::V1::Idempotent): the same key and request replays the first 2xx answer (status and body), another request answers 422idempotency_key_reused. Same table and store as MCP (Mcp::IdempotencyStore); the REST fingerprint includes method and path, so a key never crosses surfaces. Runs inside authentication and the read-only gate. A key is at most 255 bytes of valid UTF-8 without NUL (else: 422invalid_idempotency_key, nothing written). One rule for both surfaces,Mcp::IdempotencyStore.client_key(strip, blank is no key) and.storable_key?(IdempotencyStore.newraises on any other key, before the write, so a third caller cannot skip it): since MCP 0.13.1 a write tool refuses such anidempotency_keyasinvalid_inputbefore it runs, after the project and read-only gates (guardspec/requests/api/mcp_idempotency_key_bound_spec.rb; it used to write, fail to remember the key with -32603 and write again on every retry). A replay checks no rights (it repeats what the same token already got; keys do not expire), and a retry must send the same bytes. Multipart bytes Rack accepts but JSON cannot encode are fingerprinted without decoding, so the action still applies its permissions and input validation. Existing JSON fingerprints stay unchanged. Every write route must beidempotent(spec/architecture/api_v1_writes_idempotent_guard_spec.rb).- ⚠️ A
rescue_fromhandler runs outside the token owner's language: the action'saround_action :with_token_owner_localehas ended by then. A text built at the raise is right; one built in the handler needswith_token_owner_locale { ... }(TermsController#glossary_forbidden). - One strict reading of a page value: the lists that refuse a
page/per_pagethey cannot read (the glossary on both doors; over REST the people directory, knowledge and meetings) read it throughListPaging.strict_number: a whole number from 1 to the maximum (as text digits only, as a JSON number also2.0), absent or empty the default, one wording in the token owner's language. Each door keeps its own error class and status (400 or 422). A new strict list uses it; the inbox, the posts of a ticket andlist_projectskeep rules of their own (they clamp). Guard:spec/services/list_paging_spec.rb. GET /api/v1/menamesapi_versionandcapabilitiesfromApi::V1::Capabilities, pinned against the routes both ways (spec/requests/api/v1/capabilities_spec.rb): a new endpoint adds its line there. Additive changes bump the minor.
POST /api/v1/tickets/:ticket_id/time_sessions books by the rule the MCP tool
create_time_session books by (REST R6, 2026-10-29; feature time_sessions.book in
/me): TimeSessions::Booking refuses no duration, both duration_string and
duration_minutes, duration_minutes that is no whole number, and an occurred_on that is
no ISO 8601 date or timestamp (422
validation_failed/invalid_input, inside the read gate), dates the booking as the
calendar day in the token owner's profile zone (stored as midnight; absent = today there),
and writes through Actors::SaveTimeSession; an unexpected actor failure (internal_error)
answers 500 without its message. Rights stay in the controller. A booking
writes no activity and no notification; it touches the ticket's updated_at. Guard:
spec/requests/api/v1/time_session_booking_spec.rb.
Ticket view (REST R1, 2026-10-29, API 1.3.0):
GET /projects/:project_id/ticketsnamesmeta.available_statuses, the project's status keys from the same source as MCPlist_tickets.GET /tickets/:idtakes opt-in pages: any one ofposts_page,posts_per_page(at most 50, above is 422),posts_order(oldest,newest),attachments_page(10 per page) switches the answer to the paged fields of MCPget_ticket(posts_total,posts_truncated,attachments, ...). Without them the body stays what it was (the contract records it; gboyke/lalabase-mcp reads it and passes it on), but for the additiveattachmentson a comment since R7, below. Invalid values: 422invalid_input, checked before the ticket is looked up. A key without a value switches too. REST does not truncate bodies, nor the extractedtextof attachments (up to 10 per page). Theseattachmentsare the ticket's own files only, with text and without URL (attachments_totalcounts those);GET /tickets/:id/attachmentslists ticket and comment files with signed URLs.GET /projects/:project_id/tickets/number/:numberanswers whatGET /tickets/:idanswers, paging included. Missing, malformed (abc,0), unreadable, out of reach or foreign: the same 404. The number is looked up only inside that project.GET /tickets/:ticket_id/posts/:id: one readable comment, whole, in the shape of a comment in the ticket. Hidden private, foreign and missing comments: the same 404.- Options and pages come from
Tickets::Reading, shared with MCPget_ticket; MCP keeps its caps. Guard:spec/requests/api/v1/ticket_view_spec.rb. - A comment lists its files (REST R7, 2026-10-30, API 1.8.0, MCP 0.14):
attachmentsbesideattachments_count, wherever a comment is served (Tickets::Serializer#post_payload: the ticket, whole or in pages, the number route, the comment route, MCPget_ticket), each withid,filename,content_type,byte_size, in id order. ⚠️idis thePostDocument's, which the file proxy takes (/org/:org/files/post_document/:id), NOT the Active Storage attachment's thatGET /tickets/:id/attachmentshands out with a signed URL. No URL and no text, soget_ticket's caps hold as they were. No capability: a client takes the field's presence as the signal. Visibility is the comment's (readable_by), no second rule.attachments_countcounts rows: a document that lost its blob stays in the count and leaves the list. Guard:spec/requests/api/v1/comment_files_spec.rb.
GET /api/v1/time_sessions/open lists the person's own open hours within the token's
reach, organisations AND projects, and only the rows the web time list shows them
(TimeSessions::ViewingScope). A booking on a ticket they cannot read keeps its row and
its minutes, with ticket: null. Owner: TimeSessions::OpenHours; guard:
spec/requests/api/v1/time_sessions_open_access_spec.rb.
GET /api/v1/organisations and GET /api/v1/projects read through
PersonalAccessTokens::ReachListing, the reader of the MCP tools list_organisations and
list_projects (MCP 0.15.0). The rows are the same, the rest differs on purpose: REST answers 200
with [] for an organisation out of reach and shows an admin archived projects unpaged and uncut;
MCP answers not_found, shows archived projects on request, pages by 100 and cuts a description.
MCP also lists only what the project gate opens; REST lists what the policy scope shows, which
is wider for a role holding nothing but time tracking.
Guards: spec/services/personal_access_tokens/reach_listing_spec.rb,
spec/requests/api/mcp_list_projects_spec.rb, spec/requests/api/v1/projects_listing_spec.rb.
GET /api/v1/projects/:project_id/knowledge (REST R2, 2026-10-29, API 1.6.0, capability
knowledge.search) lists a project's notes and documents by title through Knowledge::Lookup,
the read the MCP tool search_knowledge uses: the same rows, order (updated_at newest first,
then id), fields (type, id, title, updated_at, link) and total for the same search.
Rows only through the per-type policy scope: no title and no count of a type the reader may not
read; a reader who may open the project but read no knowledge gets an empty list. Without q
(or blank) REST lists every readable row; MCP keeps q required. type other than note or
document, and page/per_page that are no whole number from 1 to the maximum (per_page at
most 100, where MCP clamps) and a NUL in q or type answer 422 invalid_input, checked
before the project; an absent or empty page/per_page is the default. A page beyond the total
reads no rows. The project gate is MCP's (token reach and ProjectAccessService): missing,
malformed, beyond the reach, not openable (an archived project for a non-admin included) and foreign answer the same 404.
Guards: spec/requests/api/v1/knowledge_spec.rb, spec/services/knowledge/lookup_spec.rb.
GET /api/v1/projects/:project_id/meetings and GET /api/v1/meetings/:id (REST R8, 2026-11-03,
API 1.10.0, capabilities meetings.list, meetings.show; no MCP tool) read a project's meetings
and one meeting. Fields are Meetings::Serializer's two allowlists: a row has no text of the
meeting, the whole answer adds participants (names only), generated_summary (Markdown),
notes, transcript (uncut, a leading metadata block left off as on the web), updated_at,
path. creator.name is null when the account is gone, the id stays. No analyses, ticket suggestions or linked tickets: each has a visibility rule of its own.
The list runs Meetings::ListQuery, the web list's order (occurred_at, then the entry time,
then id, all newest first) and Meeting.search_by_content, on policy_scope(project.meetings)
and nowhere else, because the search matches inside transcripts. Paging and q by the strict
rule of knowledge, before the project (a 422 says nothing about it). The list's gate is
Api::V1::ReadableProject, shared with knowledge; a reader without the meetings area gets an
empty list. Api::V1::ReadableMeeting answers one 404 in status and body for missing, malformed,
out of reach, foreign and no area, and turns a policy refusal into that 404 as well: unlike a
ticket, a meeting never answers 403. An archived project is the web's: closed to a member, open
to an account admin. Guard:
spec/requests/api/v1/meetings_read_spec.rb.
GET /api/v1/organisations/:organisation_id/people and .../people/:id (People S3b) read
the people directory through People::Lookup, the object the assistant's find_people /
get_person and their MCP twins read as well: one rights question (the people right, 403
without it), one search, one field selection (a list row never carries contact details or
notes; the card carries the notes, MCP and the assistant never do). Only a token that
reaches every project of the organisation reads its directory: a token limited to some
projects, an organisation outside the token (a deactivated membership included) and a
missing one answer the same 404, as do a missing and an invisible person. The list pages
by 50, at most 100; a value outside is a 400, never cut. Guards:
spec/requests/api/v1/people_spec.rb, spec/requests/api/mcp_people_spec.rb,
spec/requests/api/people_parity_spec.rb (REST and MCP answer the same rows).
GET /api/v1/organisations/:organisation_id/terms (K4c, 2026-11-06, API 1.11.0, capability
terms.list) and the MCP tool get_glossary (MCP 0.18.0, :mcp only) read an organisation's
glossary through Glossary::Lookup, for a device that hands the terms to its speech recognition
and replaces learnt wrong forms before it sends. Only what works: confirmed terms, and at them the
heard forms of TermCorrection.effective (a confirmed term without one has an empty heard),
grouped by the compared form with the spelling last heard, count the sum of replaced_count,
speakers as refs of the people directory. The glossary right of the token's owner
(GlossaryPolicy, an active membership) or 403 with reason: glossary_forbidden (MCP refused,
the same reason and text). Unlike the people directory, a token limited to some projects is
answered: every term, the heard forms of its projects only, and a form without a project only for
a token that reaches every project. An organisation outside the token, a foreign, a missing and a
malformed one answer the same 404 (MCP not_found, also for a malformed id); a member deactivated in
an organisation the token names gets the 403 of the missing right instead (the reach still leaves that
organisation out, PersonalAccessToken#deactivated_member_of? only words the refusal), a removed
membership the 404; project_id puts the
forms of its project first, outside the organisation or the token the same 404. people and
speakers only with the people right (PersonPolicy), named as the directory names them to the
reader; whom it does not list counts in count alone. No meeting, place or corrector in the
answer. Pages by 50, at most 100, a whole number outside is a 400 (MCP invalid_input, the same text
after the same checks: the bounds are the reader's, not the tool schema's). The types stay the schema's:
a value of another type, null included, the MCP SDK refuses before any tool runs, in its own words,
as for every tool; a whole number written as 2.0 is one (JSON Schema's integer). Guards:
spec/requests/api/v1/terms_spec.rb, spec/requests/api/mcp_glossary_spec.rb,
spec/requests/api/glossary_parity_spec.rb (REST and MCP answer the same),
spec/services/glossary/lookup_spec.rb.
POST /api/v1/tickets/:ticket_id/posts (REST R3a) writes by the rule the MCP tool
post_comment writes by, Posts::Comment, through Actors::SavePost like the web form:
post[format] html (the default, the body stored as sent) or plain (literal text through
Posts::PlainTextBody: escaped, blank lines into paragraphs, single breaks into <br>). An
unknown format, one that is no string (read raw: strong parameters would drop a list and fall
back to html), NUL in a plain body and a plain body that converts to nothing answer 422
validation_failed/invalid_input with a text from services.post_comment.*, checked inside
the read gate. Without format the answer stays byte for byte: an empty body is the model's
refusal, after the write check, with every model message (the contract case html_empty was
recorded before R3a), and a JSON false as body counts as none, as before. Raw invalid bytes
in a form or JSON body never reach the rule (the 400 above); MCP refuses them. Only a multipart
part can name a charset of its own (text/plain; charset=...): html hands it to ActionText as
it came, as before (a Latin-1 comment keeps its letters), plain transcodes it to UTF-8, and a
plain part declared binary must hold UTF-8. An unexpected actor failure (internal_error) answers 500 without the exception's
text, every other failure 422 validation_failed as before; MCP answers comment failed: unexpected error. ⚠️ A failure after the commit (an after_commit callback or a job enqueue
that raised) leaves the comment written: Posts::Comment#save counts it as saved, so REST
answers 201 and keeps its Idempotency-Key, and MCP returns the comment. Answered as an error,
a retry with the same key wrote it twice, because the key keeps only successes. Capability
posts.plain. Guards:
spec/requests/api/v1/post_comment_format_spec.rb, spec/services/posts/comment_spec.rb,
spec/requests/api/mcp_plain_comment_spec.rb, spec/locales/token_rule_refusal_texts_spec.rb
(the refusals of Posts::Comment, TimeSessions::Booking and Tickets::Change, the MCP texts and
the de and en keys are three lists kept by hand; the guard holds them together).
POST /api/v1/tickets/:id/changes (REST R3b, 2026-10-30, API 1.7.0, capability
tickets.changes) changes ONE thing by the rule the MCP tool update_ticket changes by,
Tickets::Change: change[title], change[status] (a key of meta.available_statuses), or
change[add_assignee_ids] and change[remove_assignee_ids] (at most 50 each, "me" is the token
owner) against the current list. The kind is decided by the keys present, not their values. It
answers 200 with the ticket summary, like PATCH /tickets/:id, which stays as it is: its
assignee_ids REPLACE the list, and gboyke/lalabase-mcp relies on that. parent_id on that
PATCH reaches the model (Ticket#parent_unchanged, a saved ticket keeps its parent): another
parent or an empty value is a 422 validation_failed/invalid_input, the current parent is no
change, so a client may send back what it read. That PATCH writes and answers under the same row
lock in the authorized project (locked_ticket in the controller, since 2026-11-05: a move after
the rights check let it write into a project the caller may not write; guard
spec/requests/api/v1/ticket_update_concurrency_spec.rb). Status and assignees
go through Actors::ApplyTicketChanges like a board drag (a TicketBulkRun included), the title
through Actors::SaveTicket alone under a lock on the row in its project, so the side effects are
the web's and MCP's, once. Order: read-only token 403, then the read gate (missing, malformed,
foreign, out of reach, hidden: one 404, whatever the body), then authorize :update? (403, whatever
the body), and only then the input, so a refusal of it only ever answers a caller who may write. A
body Rails cannot read comes before the gate: a 400, the same for every ticket.
Input refused (mixed kinds, an unknown key, no change, the title rule, a list that is no list,
over 50, the same person in both lists, text that is no UTF-8): 422
validation_failed/invalid_input, a text from services.ticket_change.* that repeats nothing the
client sent. One difference to MCP is Rails', not the rule's: a JSON null in a list is gone before
the rule reads it, so [id, null] is [id] here and refused there; it names nobody either way.
Stopped by the project's state: 422 with code: refused, and error and reason the
same word (value_not_allowed, user_not_assignable, no_status_field, validation_failed), a
text from services.ticket_change_failure.* in errors and, for a title the model refuses, its
messages behind it. The code is named in the controller: Api::V1::ErrorBody alone would read
validation_failed as invalid input. Nobody is removed by a refused change, and a stale assignment
stays unless it is named. A ticket that moved or was deleted after the rights check answers the same
404. After the write commits, the response takes a fresh lock in that same project and reads
the whole summary under it, so a concurrent move cannot disclose destination data.
A failure the rule does not name answers 500 without its text. Guards:
spec/requests/api/v1/ticket_changes_spec.rb, spec/requests/api/v1/ticket_changes_side_effects_spec.rb
(the same trail as MCP), spec/requests/api/v1/ticket_changes_concurrency_spec.rb
(the response against a concurrent move), spec/services/tickets/change_spec.rb.
Admin: Betreiber-Teile kommen nur über Schlitze
Verbindlich (Guard-Spec: spec/architecture/admin_operator_boundary_guard_spec.rb; läuft über
den Verzeichnis-Eintrag spec/architecture/ in der CI-Guard-Liste):
Der Adminbereich wird geteilt (doc/oss_core_split_plan.md 5.5 bis 5.7). 17 Controller bleiben
als Instanz-Admin im Kern. Sieben werden eine private Engine, die nur ein interner Prozess lädt:
accounts, account_discounts, price_lists, billing_lists, founder_signups,
founder_signup_settings, acquisitions. Im öffentlichen Prozess und auf jeder fremden Instanz
gibt es ihre Routen nicht.
- Kein Kern-Code ruft eine Route dieser sieben Controller. Ein
admin_account_pathin einer Kern-View rendert dort keinen toten Link, er wirft, und die Seite ist weg. Der Wächter liest Routennamen und Pfade aus dem Router, nicht aus einer Wortliste, und kennt drei Formen: den benannten Helfer, das polymorphe Array ([:admin, account]) und den getippten Pfad ('/admin/accounts', auch in.js). Ein Grep sieht nur Namen:[:admin, record]mit einem Konto inrecordfindet erst der Request-Spec mit leerem Register. - Keine Ausnahmeliste. Es gab eine, mit den beiden Templates der Gründer-Mail, und sie ist seit dem 22.09.2026 leer und gelöscht.
- ⚠️ Ein Link aus dem Kern in die Konsole ist eine gespeicherte Adresse, nie eine Route. Die
Gründer-Mail rendert im öffentlichen Prozess und zeigt auf eine Seite der Konsole, die unter
einem anderen Host läuft (Tunnel). Der Betreiber hinterlegt deshalb eine Vorlage mit einem
Platzhalter (
SystemSetting.founder_signup_console_url,%{account_id}), und der Kern setzt nur die ID ein. Leer heißt: kein Link. Eingesetzt wird per Ersetzung, nicht mitKernel#format: das wirft bei einem zweiten Platzhalter oder einem losen Prozentzeichen, und zwar in einem Mailer-Job, für einen Wert, den jemand Wochen vorher getippt hat. - Eine Kern-Seite, die einen Betreiber-Abschnitt zeigen soll, nennt einen Schlitz:
<%= admin_extension_slot(:user_sections, user: @user) %>. Wer geladen ist, meldet ein Partial an (Lalabase::AdminExtensions.register). Ohne Anmeldung rendert der Schlitz nichts. - Die Schlitz-Liste ist eine geschlossene Konstante (
Lalabase::AdminExtensions::SLOTS). Ein vertippter Name wirft, statt auf einer Seite still nichts zu rendern, auf der „nichts" ein gültiger Zustand ist. Ein neuer Schlitz heißt: Konstante ergänzen. - Anmelden nur in
config.to_prepare.lib/wird automatisch geladen; ein Code-Reload ersetzt das Register,to_prepareläuft danach erneut. - Der Controller einer Kern-Seite lädt nichts, was nur die Konsole zeigt. Das Partial holt es
sich selbst (Vorbild:
Admin::Operator::UserBillingAccounts). - Wie der öffentliche Prozess den Admin ausliefert, hält
spec/requests/admin/without_operator_extensions_spec.rbfest: die Seiten mit leerem Register (Lalabase::AdminExtensions.with_empty_registry).
Was lalabase.com über diesen Code behauptet
Die öffentlichen Seiten liegen seit W3 in gboyke/lalabase-website und können den Code nicht
mehr lesen. Drei Wächter in spec/architecture/ halten die Verbindung, alle über den
Verzeichnis-Eintrag automatisch in der CI-Guard-Liste:
| Wächter | Hält |
|---|---|
website_quoted_facts_guard_spec.rb |
Werte, die eine Seite wörtlich nennt: Devise confirm_within, UnconfirmedSignupPurgeJob::RETENTION, AcquisitionSource::RETENTION, FounderSignup::REVENUE_BANDS, der path_prefix-Default. Die Website hält die Kopie in CoreFacts |
website_feature_claims_guard_spec.rb |
Mechanismen hinter den Zusagen der Funktionsseiten: keine Stoppuhr, keine Beträge, sieben Schalter, nur GitHub und GitLab, Chat schreibt nicht, … |
ai_provider_disclosure_guard_spec.rb |
Welche KI-Anbieter der Code anbieten kann. Die Datenschutzerklärung drüben muss jeden davon formell nennen; hier steht die Hälfte, die nur dieses Repo beantworten kann |
- Rot heißt hier nie nur „Code". Entweder die Änderung ist falsch, oder ein Satz auf einer öffentlichen Seite ist gerade unwahr geworden und muss dort umgeschrieben werden. Die Fehlermeldung nennt die Datei im anderen Repo.
- Jeder Wächter zitiert den Satz, den er stützt; die Spec drüben nennt das Beispiel, das ihn stützt. Wer eine Seite ändert, findet die Mechanik, und umgekehrt.
- ⚠️ Bei W6 nicht mitlöschen. Wenn der Kern seine Kopien der Seiten entfernt, gehen die
Seiten-Specs mit. Diese beiden bleiben: sie sind das Einzige, was eine öffentliche Zusage
noch an den Code bindet (
doc/oss_core_split_plan.md§ 11.4).
Third-party licenses: every dependency is permissive
Binding (guard spec: spec/architecture/third_party_license_guard_spec.rb; runs through
the directory entry spec/architecture/ in the CI guard list):
The core is AGPL-3.0-only and has one copyright holder. While every dependency is permissive, how this
project is licensed is that holder's decision alone. One dependency under GPL or AGPL alone
ends that, and a bundle update can bring one without anybody noticing.
| What | Rule |
|---|---|
| Gems (the installed bundle) | every declared license is on the allowlist: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, Ruby |
npm packages (package-lock.json) |
the same rule, without exceptions |
| Third-party code checked into the repository | every file has a Path: line in THIRD_PARTY_NOTICES.txt, and its section states a license from the same list (plus OFL-1.1 for fonts) |
- Every declared license has to be allowed, not one of them. A gemspec does not say whether
its list is a choice (
ttfunk: Ruby terms or GPL) or a sum (nio4r: MIT plus BSD for the bundled libev). A real choice is an entry inGEM_EXCEPTIONS, with the license taken and the reason. GEM_EXCEPTIONSonly shrinks (nine entries on 2026-09-30). An entry holds while the gemspec declares what the entry recorded: a gem that changes its declaration turns red and has to be read again. An entry for a gem that left the lockfile, or that would pass on its own, is red as well.- Every gem of the lockfile is read, not only the installed ones. A bundle installed
without a group turns red instead of checking less. The three build tools that are
installed on no platform we run stand in
NOT_INSTALLED, read by hand. - Red after a
bundle updatemeans: read the license text of the new gem. GPL or AGPL alone: find another gem. - What counts as checked-in third-party code: everything git tracks under
vendor/,public/fonts/andapp/assets/stylesheets/bootstrap-icons/, and anywhere else a file named*.min.js,*.min.cssor like a font, and a script or stylesheet underapp/orlib/that opens with a license header. The paid theme scripts lived inapp/javascriptuntil #814, outside every vendor directory. - A notice is not a permit. A new vendored file needs its name, version, source,
License:and copyright line inTHIRD_PARTY_NOTICES.txt, and the guard reads theLicense:line: a GPL file with a tidy notice is still red. A directoryPath:may not lie above another entry (Path: vendor/would cover everything to come). - ⚠️ Not covered, because no lockfile and no file name shows it:
- what a gem carries inside itself: the Rust crates compiled into
commonmarker, native libraries (the macOS build ofnokogiriships LGPLlibiconv, the Linux build does not), the JavaScript insidelexxy,turbo-railsandstimulus-rails, the gemsbrakemanvendors; - system libraries loaded into the process (
libvips, LGPL, throughruby-vips); - programs the application calls as separate processes (ImageMagick; for PDF previews Poppler or MuPDF);
- a release that changes its license text and keeps its gemspec: an exception is tied to the declaration, not to the version;
- single icon paths copied into views (Heroicons, Lucide) and locale files generated by
gems (
pagy,devise).
- what a gem carries inside itself: the Rust crates compiled into
Development Checklisten
Multi-Tenancy
-
acts_as_tenantgesetzt? - Default-Scope korrekt?
- Seeds/Factories tenant-aware?
- Queries filtern korrekt auf tenant?
Security & Authorization
- Strong Parameters korrekt?
- Pundit Policies angewendet?
- Negative Tests: Unberechtigte bekommen 403?
- Positive Tests: Berechtigte dürfen Aktion?
Performance
- N+1 Queries vermieden mit
includes/joins? - Indizes für neue komplexe Queries?
- Caching-Strategie bedacht?
i18n
- Alle neuen User-facing Strings via
t()eingebunden? - Keys in DE UND EN der passenden Bereichsdatei (
config/locales/views/<bereich>.{de,en}.yml) angelegt? - Geänderte Texte in DE UND EN nachgezogen, auch wenn nur eine Sprache besprochen wurde?
- Keine hardcoded deutschen/englischen Strings in Views/Controllers?
- JavaScript-Strings über ERB oder
data-*Attribute übersetzt?
Code Quality
- Tests grün:
rspec - Linter clean:
rubocop,erblint - Security clean:
brakeman - Policies geprüft/neu angelegt
Häufige Scripts & Hilfsmittel
- Style Guide: Entwicklung unter
/style-guideverfügbar - Wording der öffentlichen Seiten ändern:
/de?wording=1schaltet in Development den In-Place-Editor ein (?wording=0aus). Text anklicken, Deutsch und Englisch stehen nebeneinander, Speichern schreibt zeilengenau inconfig/locales. Nurstatic.*, nur Development, keine mehrzeiligen Werte. Details:lib/dev/wording_mode.rb - Server-Betrieb (Backup, Log-Retention):
ops/backup/— Skripte, systemd-Units und logrotate-Konfigurationen der Produktion, plus Restore-Anleitung inops/backup/README.md. Die Dateien werden nicht automatisch ausgerollt: bei Änderungen Repo und Server nachziehen. Unsere konkreten Koordinaten stehen hier nicht (Storage-Box-Unterkonten, Hosts, Schlüsselpfade): die Skripte lesen sie zur Laufzeit aus/etc/lalabase-backup/backup.conf(Vorlage:ops/backup/backup.conf.example) und brechen ohne sie laut ab.
Authentication für Development
- Für die Entwicklung ein lokales Demo-Konto anlegen.
- Demo aus den Seeds (frische Dev-Datenbank):
[email protected](Admin),[email protected](Standardrolle),[email protected](Projektmanager),[email protected](Betrachter),/adminmit[email protected], Passwort jeweilslalabase-demo
Internationalisierung (i18n)
Grundregel
NIEMALS hardcoded User-facing Strings in Views, Controllers, Models oder Mailers. IMMER t() verwenden.
Locale-Struktur
- Dateien: View-Strings liegen pro Bereich in
config/locales/views/<bereich>.{de,en}.yml(tickets, ansichten, zeiterfassung, meetings, inbox, wissen, dokumente, hilfe, organisation, personen, glossar); Rest (common/shared/layouts/devise/admin/components) inviews.{de,en}.yml. Unterordner werden von Rails automatisch geladen. Cross-File-Duplikate mit abweichenden Werten bricht der Guard (spec/locales/no_duplicate_keys_guard_spec.rb) — jeder Key hat genau EINEN Besitzer. - Key-Konvention:
views.organisations.<controller>.<action>.<key>für Views - Shared Keys:
views.organisations.<controller>.shared.<key>für partialübergreifende Strings - Flash Messages:
controllers.<controller>.<action>.<key> - Models/Validations:
activerecord.errors.models.<model>.<key> - Zahlen/Beträge:
rails-i18nist nicht eingebunden — die Formate stehen selbst gepflegt unternumber.*inde.ymlunden.yml. Ohne den DE-Zweig fälltnumber_to_currency& Co. lautlos auf die englischen Rails-Defaults zurück und die deutsche Oberfläche zeigt „€14.50" statt „14,50 €". Preisbeträge nie selbst formatieren, sondern überPriceHelper#format_price_cents(Guard:spec/helpers/price_helper_spec.rbpinnt beide Locales). - Aufzählungen: Aus demselben Grund steht
support.arrayselbst gepflegt inde.ymlunden.yml. Ohne den DE-Zweig verbindetto_sentenceauf deutschen Seiten mit „, and" („Status, Priorität, and Titel"), auch in jeder Flash-Meldung, die Validierungsfehler aneinanderreiht (Guard:spec/helpers/timeline_helper_spec.rb). - Dates (guard:
spec/architecture/locale_date_format_guard_spec.rb): a date on a page goes throughl()with a named format fromdate.formats/time.formats, never throughstrftimewith a format of its own. strftime writes English month names on the German page, and a typed%d.%m.%Yis German on the English one. A literal format stays only where it reads the same in both languages (ISO dates, the clock, month or day names alone throughl()). The legacy list (51 formats in 29 files on 2026-10-18) only shrinks.
Die Sprache einer Anfrage (seit 20.08.2026, Kern-Fassung seit D5)
Die öffentlichen Seiten liegen seit W6 in gboyke/lalabase-website, die Dokumentation seit
D5 in gboyke/lalabase-documentation. Was hier blieb, ist die Frage, in welcher Sprache der
Kern antwortet.
- Entschieden wird sie in
ApplicationController#switch_locale, einemaround_actionvorauthenticate_user!(Devise übersetzt seine Anmelde-Hinweise in der Sprache, die in diesem Moment gilt). Reihenfolge: gültiges?locale=, Profilsprache eines Angemeldeten, gemerkte Sprache dieser Sitzung (session[:public_locale]),Accept-Language, Deutsch. Im Demo-Modus (LALABASE_DEMO=1) gilt davor immerLalabase::Demo::LOCALE: Die Welt ist in dieser Sprache geschrieben, und das geteilte Konto darf keine Wahl festhalten (Guard:spec/requests/demo_mode_spec.rb). Ein gültiges?locale=wird gemerkt. Die Registrierung übernimmt die Sprache des Formulars ins Profil. Guard:spec/requests/locale_per_request_spec.rb. ⚠️ Über dieser Leiter stand eine Sprosse: die Sprache im PFAD./docs/:locale/…waren die letzten Routen, die eine trugen, und sie sind mit D5 weg (die öffentlichen Seiten nahmen ihre bei W6 mit).request.path_parameters[:locale]kann von keiner Route mehr gesetzt werden, also ist die Sprosse gelöscht statt ungeprüft behalten. Wer eine Route mit Sprache im Pfad baut, holt sie zurück: zuerst lesen, und wie?locale=merken. - ⚠️
I18n.localeist Thread-Zustand und überlebt die Anfrage.switch_localesetzt es perI18n.with_localeund stellt es danach zurück; eine Action darf es darin umsetzen (die Spracheinstellung). Außerhalb dieses Rahmens, etwa in einem Controller, der nicht vonApplicationControllererbt, bleibt es für die nächste Anfrage auf demselben Puma-Thread liegen. Genau so bekamen Registrierung und Login bis zum 10.09.2026 die Sprache der vorigen Anfrage. - Die Sprache kommt aus
request.query_parameters['locale'], nicht ausparams:paramserzwingt das Parsen des Request-Bodys, und dieser Callback läuft auf jedem Controller, auch auf den Mail-Webhooks mit ihren fremden Nutzlasten. - Welche Sprachen es gibt, beantwortet I18n, nicht mehr eine Tabelle der öffentlichen
Seiten (
supported_locale). Ein fehlender englischer Text ist dabei nicht laut:config/initializers/i18n.rbsetztfallbacks = [:de].
Rechtsangaben gehören dem Betreiber, nicht uns
Der Kern hostet keine Rechtsseiten und nennt unsere Firma nirgends. Betreibername und die
Adressen von Impressum, Datenschutz und AGB stehen in den Systemeinstellungen
(LegalIdentity, vier SystemSetting-Zeilen, eine Abfrage je Anfrage über Current).
- Gerendert wird ausschließlich über
legal_operator_credit,legal_page_linkundlegal_footer_links. Ohne Betreibername steht dort der übersetzte Textpowered by Lalabase, ohne Adresse erscheint kein Link. - Wer keine eigene Website hat, schreibt den Text im Adminbereich; die Instanz liefert
ihn unter
/legal/<seite>aus (LegalPagesController, Markdown, sanitisiert). Eine eingetragene Adresse gewinnt über den Text. - ⚠️ Kein Kern-Code liest die öffentliche Website: keine
StaticHelper-Konstante, keine öffentliche Rechts-Route, keinstatic.*-Text. Guard:spec/architecture/app_legal_identity_guard_spec.rb, ohne Ausnahmeliste. - Was lalabase.com über diesen Code behauptet, halten zwei weitere Wächter fest — siehe den eigenen Abschnitt dazu.
Der Kern wirbt nicht für unsere Cloud
Verbindlich (Guard-Spec: spec/architecture/app_operator_claims_guard_spec.rb; läuft über
den Verzeichnis-Eintrag spec/architecture/ in der CI-Guard-Liste):
Die Seiten ohne Anmeldung liest ein Besucher, der nicht weiß, auf wessen Instanz er ist. Was
dort steht, muss der Betreiber sagen können, nicht nur wir. Bis zum 20.09.2026 stand auf
jeder Anmeldeseite „Hosting in Deutschland | AVV inklusive", in der Fensterleiste des Panels
lalabase.app/inbox, und die Registrierung bot unseren Gründerrabatt an.
Der Wächter prüft die I18n-Bereiche der sieben Seiten ohne Anmeldung gegen fünf Muster:
| Muster | Beispiel |
|---|---|
| unsere Domain | lalabase.app, lalabase.com |
| Ort des Hostings | „Deutschland", „Germany", „hosted" |
| Vertrag mit uns | „AVV", „DPA", „Auftragsverarbeitung" |
| Preis oder Rabatt | „50 %", „14,50 €" |
| Zahlungsbedingungen | „Rechnung", „kündbar", „Abo" |
Dazu die Auszeichnung selbst: kein lalabase.* in app/views/devise/** und im Auth-Layout.
Der Instanz-Name kommt aus request.host.
- ⚠️
app_legal_identity_guard_spec.rbdeckt das NICHT ab. Es suchtStaticHelper::, öffentliche Rechts-Routen undt('static.. Diese Texte lagen unterviews.devise.*, weil die Keys eigens aus der Preisseite herauskopiert wurden, damit sie nicht mehrstatic.*heißen. Die Zusage ist dabei mitgewandert. Zwei Wächter, zwei Fragen: der eine hält den Kern von der Website fern, dieser von unserem Geschäft. - Keine Ausnahmeliste. Es gab eine, mit einem Eintrag, und der Gründerrabatt verließ das Registrierungsformular am 20.09.2026. Eine leere Liste lädt den ersten neuen Eintrag ein.
- ⚠️ Die Auszeichnung wird mit weggeschnittenen ERB-Tags gelesen
(
AppOperatorClaimsGuard.literal_text). Sonst liest sich<%= index + 1 %>als „1 %" und schlägt beim Preismuster an, und jeder Kommentar, der eine entfernte Zusage erklärt, schlägt bei ihrem eigenen Muster an. - Die Vorzeile einer Auth-Seite nennt einen Zustand („Konto gesperrt", „Bestätigung fehlt"), nie eine Zusage.
Bei jedem neuen Feature / jeder Änderung
- Bestehende Texte ändern → IMMER beide Sprachen. Eine Wording-Änderung an einem deutschen Text ohne die englische Fassung ist unfertig, und sie fällt niemandem auf: der Key existiert, die Seite rendert, nur der Satz ist veraltet. Gilt auch dann, wenn nur die deutsche Seite besprochen wurde (Anweisung des Users, 21.08.2026).
- Neue Strings → sofort als
t()Call schreiben, Key in DE + EN Locale anlegen - Bestehende Views ändern → prüfen ob noch hardcoded Strings vorhanden sind, ggf. gleich mit extrahieren
- JavaScript-Strings → über ERB-Interpolation (
<%= t("...") %>) in.js.erboder viadata-*Attribute - Confirmation-Dialoge → Keys unter
views.confirm.<key>in beiden Locales
Beispiel
<%# ✅ Richtig %>
<h1><%= t('views.organisations.tickets.index.title') %></h1>
<%= link_to t('views.organisations.tickets.shared.back'), tickets_path %>
<%# ❌ Falsch — hardcoded String %>
<h1>Aufgaben</h1>
<%= link_to "Zurück", tickets_path %>
Konstanten & Magic Numbers
- Keine "Magic Numbers/Strings" im Code – in Konstanten (
ALL_CAPS) oder I18n auslagern - Konstanten in thematischen Namespaces bündeln:
Notifications::Constants::EVENT_TYPE_MAPPING - Immutable machen (
.freezebei Arrays/Hashes) - Thread-safe Zugriff in Background Jobs:
Notifications::Constants::EVENT_TYPE_MAPPING
Code-Review Checklist
- Tests grün & vollständig (System-, Request-, Unit-Tests)
- Regressions-Test bei Bugfix hinzugefügt
- Policies geprüft/neu angelegt & Tests vorhanden
- Linter & Security-Scanner clean
- Multi-Tenancy korrekt implementiert
- Background Jobs verwenden thread-safe Konstanten-Zugriff
- ViewComponents folgen Neo-Brutalist Design System
- i18n: Alle Strings via
t(), Keys in DE + EN vorhanden