m/paliad
1
0
Fork 0
Code Issues 146 Pull Requests 8 Actions 2 Packages Projects Releases Wiki Activity

design: data model v2 — Mandanten + nestable Projekte + Teams (t-paliad-023)

Browse Source 
Comprehensive design doc for the replacement of flat paliad.akten with:
  - paliad.mandanten (Clients as first-class table)
  - paliad.projekte (single self-referential typed tree, ltree materialised
    path, 5 project types: mandat/litigation/patent/verfahren/projekt)
  - paliad.teams + paliad.team_mitglieder (Dezernate + project teams in one
    table with kind-shape CHECK)
  - paliad.projekt_mitglieder (hot-path junction replacing akten.collaborators)

Polymorphic FK strategy: single project_id FK on fristen/termine/dokumente/
parteien/akten_events/checklist_instances. Notizen keeps its 4-way polymorphic
shape (akte_id renamed to project_id).

Visibility model: tree-connected — seeing any node grants access to the whole
tree (ancestors + descendants). Office-scope stays at project level; Mandant-
level firm_wide_visible / collaborators override.

Migration plan: 6 phases, non-destructive. UUIDs preserved between akten and
projekte rows so child tables only need column renames, no data moves.

Opinionated: German naming throughout (mandanten, projekte, teams,
team_mitglieder, projekt_mitglieder); /akten URLs alias to /projekte
indefinitely; akten_events table name kept for continuity.

Deliverable: docs/design-data-model-v2.md (920 lines, 14 sections).
This commit is contained in:
m
2026-04-20 14:17:32 +02:00
parent b370d59eee
commit fabe32aa56
1 changed files with 920 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

920
docs/design-data-model-v2.md Normal file
View File

@@ -0,0 +1,920 @@
# Data Model v2 — Clients, nestable Projects, Teams
**Author:** cronus (inventor)
**Date:** 2026-04-20
**Task:** t-paliad-023
**Status:** Design draft for review. Supersedes the flat `paliad.akten` model in `design-kanzlai-integration.md` §2–§3.
**Scope:** Schema + migration plan. No implementation in this change.
---
## Executive summary
**Recommendation.** Replace the flat `paliad.akten` table with a two-table core:
1. `paliad.mandanten` — clients (companies or people who instruct HLC).
2. `paliad.projekte` — a **single, self-referential, typed tree** of all work. Every row has a `project_type` (`mandat`, `litigation`, `patent`, `verfahren`, `projekt`), an optional `parent_project_id`, and a required `client_id` that points to the Mandant at the root of the tree. Fristen, Termine, Notizen, Dokumente and Parteien all hang off a **single polymorphic `project_id`** — "polymorphic" only in the sense that any node in the tree can own them, not in the sense of multi-table FKs.
**Teams** become explicit rows. `paliad.teams` holds both Dezernate (structural, one partner-led unit per row) and — as a separate concept — Project Teams (ad-hoc, per-project roster). The `paliad.users.dezernat` free-text field is superseded by `paliad.team_mitglieder`. The `paliad.akten.collaborators uuid[]` array on every Akte is replaced by `paliad.projekt_mitglieder`, giving us per-user roles inside a project and a sane target for audit + invitations.
**Visibility** stays office-scoped, but the predicate now walks the tree: seeing *any* node in a project grants the viewer access to the whole connected tree (root, siblings, descendants). This matches how lawyers actually use the data — a Munich associate put on one UPC Case of a Siemens litigation must see the parent litigation and the sibling Cases to do their job, and a lead partner put on the litigation root must see everything below.
**Naming.** Stay German, matching everything shipped so far — `mandanten`, `projekte`, `teams`, `team_mitglieder`, `projekt_mitglieder`. German plural for table names, singular for Go structs (`Mandant`, `Projekt`, `Team`). `User` stays English (Supabase concept).
**Migration** is phased and non-destructive. Existing `paliad.akten` rows survive as `projekte` rows with `project_type='verfahren'` (best match for the flat-Akte pattern), the same primary key UUIDs, and `client_id` nullable during a cleanup window (the partner UI collects real Mandant assignment). Every child table (`fristen`, `termine`, `notizen`, `dokumente`, `parteien`, `akten_events`, `checklist_instances`) gets its FK column renamed from `akte_id` to `project_id` in a follow-on migration — no data move, just a DDL rename. The existing `/akten` URLs stay live as aliases of `/projekte`.
**This is the foundation for Paliad v2.** It is opinionated. The trade-offs are called out inline.
---
## 1. Entity-Relationship
### 1.1 Mermaid
```mermaid
erDiagram
USERS ||--o{ TEAM_MITGLIEDER : "belongs to"
USERS ||--o{ PROJEKT_MITGLIEDER : "staffed on"
TEAMS ||--o{ TEAM_MITGLIEDER : "has members"
MANDANTEN ||--o{ PROJEKTE : "owns"
PROJEKTE ||--o{ PROJEKTE : "parent of"
PROJEKTE ||--o{ PROJEKT_MITGLIEDER : "has team"
PROJEKTE ||--o{ FRISTEN : "1:N"
PROJEKTE ||--o{ TERMINE : "1:N (nullable)"
PROJEKTE ||--o{ NOTIZEN : "1:N (polymorphic parent)"
PROJEKTE ||--o{ DOKUMENTE : "1:N"
PROJEKTE ||--o{ PARTEIEN : "1:N"
PROJEKTE ||--o{ AKTEN_EVENTS : "1:N (audit)"
PROJEKTE ||--o{ CHECKLIST_INSTANCES : "1:N (nullable)"
FRISTEN ||--o{ NOTIZEN : "parent (optional)"
TERMINE ||--o{ NOTIZEN : "parent (optional)"
AKTEN_EVENTS ||--o{ NOTIZEN : "parent (optional)"
TEAMS {
uuid id PK
text type "dezernat | project_team"
text name
uuid partner_id FK "for dezernat; NULL for project team"
uuid projekt_id FK "for project team; NULL for dezernat"
text office "seat of the dezernat; NULL for project team"
bool is_active
}
MANDANTEN {
uuid id PK
text name
text legal_form "e.g., AG, GmbH, Einzelerfinder"
text industry
text country
text billing_reference
jsonb key_contacts
text owning_office "Default office for new Projekte"
uuid[] collaborators "Firm-wide people with explicit Mandant access"
bool firm_wide_visible
text status "active | archived"
}
PROJEKTE {
uuid id PK
uuid client_id FK "nullable during migration"
uuid parent_project_id FK "self"
text project_type "mandat|litigation|patent|verfahren|projekt"
text title
text reference "human-readable ref (Aktenzeichen)"
text external_ref "EP no., UPC docket, etc."
text court
text court_ref
text status "active | pending | closed | archived"
text owning_office
bool firm_wide_visible
uuid created_by FK
jsonb metadata
ltree path "materialised ancestor path"
int depth "0 = root"
}
PROJEKT_MITGLIEDER {
uuid projekt_id PK FK
uuid user_id PK FK
text role "lead|associate|pa|of_counsel|local_counsel|expert|observer"
timestamptz added_at
uuid added_by FK
}
TEAM_MITGLIEDER {
uuid team_id PK FK
uuid user_id PK FK
text role "partner|associate|pa|trainee|of_counsel|secretariat"
timestamptz added_at
}
```
### 1.2 ASCII worked example
Showing the Siemens portfolio from the brief. `[P]` = partner, `[A]` = associate, `[LC]` = local counsel. Node IDs are illustrative.
```
MANDANTEN: M1 "Siemens AG" (industry=industrial, owning_office=munich)
│
└── PROJEKTE (client_id=M1)
│
└── P0 project_type=mandat "Siemens — Overall relationship" (path=P0, depth=0)
│ owning_office=munich
│ Team: [P Lead=partner_a@munich] [A associate_b@munich]
│
└── P1 project_type=litigation "Siemens v. Huawei — SEP Portfolio" (path=P0.P1, depth=1)
│ owning_office=munich, firm_wide_visible=false
│ Team: [P Lead=partner_a@munich] [A associate_c@duesseldorf] [LC local_uk@london]
│
├── P2 project_type=patent "EP 1 234 567" (path=P0.P1.P2, depth=2)
│ │ external_ref=EP1234567
│ │
│ ├── P3 project_type=verfahren "UPC Infringement UPC_CFI_123/2026"(path=P0.P1.P2.P3, depth=3)
│ │ court=UPC_CFI_Munich, court_ref=UPC_CFI_123/2026
│ │ └─ Fristen, Termine, Notizen, Dokumente all project_id=P3
│ │
│ ├── P4 project_type=verfahren "EPO Opposition W 0001/26"
│ └── P5 project_type=verfahren "BPatG Nullity 3 Ni 45/26"
│
├── P6 project_type=patent "EP 2 345 678"
│ └── P7 project_type=verfahren "UPC Infringement UPC_CFI_456/2026"
│
└── P8 project_type=patent "EP 3 456 789"
└── P9 project_type=verfahren "LG München I 21 O 12345/26"
```
The key insight: **every box is a row in `paliad.projekte`**. Fristen/Termine/Notizen live at whichever node is the right home. Dashboard aggregates across all nodes the user can see by walking the visibility predicate.
---
## 2. Table schemas
### 2.1 `paliad.mandanten`
```sql
CREATE TABLE paliad.mandanten (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
name text NOT NULL,
legal_form text, -- 'AG', 'GmbH', 'Inc.', 'Einzelerfinder', …
industry text, -- free text, not an enum
country text, -- ISO 3166-1 alpha-2 ('DE','US',…)
billing_reference text, -- matches the firm-wide billing system
key_contacts jsonb NOT NULL DEFAULT '[]'::jsonb,
-- [{"name":"…","role":"…","email":"…","phone":"…"}]
owning_office text NOT NULL CHECK (owning_office IN (
'munich','duesseldorf','hamburg',
'amsterdam','london','paris','milan')),
-- Visibility knobs, analogous to paliad.akten today:
collaborators uuid[] NOT NULL DEFAULT '{}',
firm_wide_visible boolean NOT NULL DEFAULT false,
status text NOT NULL DEFAULT 'active'
CHECK (status IN ('active','archived')),
metadata jsonb NOT NULL DEFAULT '{}',
created_by uuid REFERENCES auth.users(id) ON DELETE SET NULL,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX mandanten_owning_office_idx ON paliad.mandanten (owning_office);
CREATE INDEX mandanten_firm_wide_idx ON paliad.mandanten (firm_wide_visible) WHERE firm_wide_visible = true;
CREATE INDEX mandanten_collaborators_gin ON paliad.mandanten USING GIN (collaborators);
CREATE INDEX mandanten_name_trgm ON paliad.mandanten USING GIN (name gin_trgm_ops);
```
Notes:
- `key_contacts` is JSONB not a child table. Contacts don't have their own identity (they're denormalised name/email/phone); pulling them into `paliad.contacts` would be overkill and block nothing. If HLC later wants CRM-style contact records, promote to a table in a follow-on.
- `owning_office` on `mandanten` is the **default** for new Projekte; individual Projekte can override.
- Duplicated visibility knobs (`collaborators`, `firm_wide_visible`) are intentional: a user can have Mandant-level visibility without being on any particular Projekt (e.g., the relationship partner who hasn't been staffed on a specific case yet). The predicate OR-fans these in.
### 2.2 `paliad.projekte`
```sql
-- Enable the ltree extension in Supabase (first migration to use it).
CREATE EXTENSION IF NOT EXISTS ltree;
-- project_type is a text + CHECK, not an enum type. Enums are painful to extend
-- in Postgres migrations; text + CHECK gives us the same validation with room
-- to add a new type by replacing the constraint.
CREATE TABLE paliad.projekte (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
client_id uuid REFERENCES paliad.mandanten(id) ON DELETE RESTRICT,
-- NULLABLE during migration;
-- enforced NOT NULL in a later phase.
parent_project_id uuid REFERENCES paliad.projekte(id) ON DELETE CASCADE,
project_type text NOT NULL CHECK (project_type IN
('mandat','litigation','patent','verfahren','projekt')),
title text NOT NULL,
reference text, -- firm-internal human ref (Aktenzeichen)
external_ref text, -- EP no., UPC docket, BPatG ref, …
court text,
court_ref text,
status text NOT NULL DEFAULT 'active'
CHECK (status IN ('active','pending','closed','archived')),
owning_office text NOT NULL CHECK (owning_office IN (
'munich','duesseldorf','hamburg',
'amsterdam','london','paris','milan')),
firm_wide_visible boolean NOT NULL DEFAULT false,
-- Materialised tree state. Maintained by a BEFORE INSERT/UPDATE trigger.
-- `path` is the ltree of ancestor ids ending with this row's id.
path ltree NOT NULL,
depth int NOT NULL CHECK (depth >= 0),
created_by uuid REFERENCES auth.users(id) ON DELETE SET NULL,
metadata jsonb NOT NULL DEFAULT '{}',
ai_summary text, -- unused today; kept from akten
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
-- Sanity: a project's client must match its parent's client (and root of
-- tree carries the single source of truth).
CONSTRAINT projekte_parent_self_differs CHECK (parent_project_id IS NULL OR parent_project_id <> id)
);
-- Trees are navigated by path. GiST over ltree makes ancestor / descendant
-- lookups <@ / @> work in O(log n) — critical for the visibility predicate.
CREATE INDEX projekte_path_gist ON paliad.projekte USING GIST (path);
CREATE INDEX projekte_parent_idx ON paliad.projekte (parent_project_id);
CREATE INDEX projekte_client_idx ON paliad.projekte (client_id);
CREATE INDEX projekte_client_type_idx ON paliad.projekte (client_id, project_type)
WHERE status <> 'archived';
CREATE INDEX projekte_owning_office_idx ON paliad.projekte (owning_office);
CREATE INDEX projekte_firm_wide_idx ON paliad.projekte (firm_wide_visible) WHERE firm_wide_visible = true;
CREATE INDEX projekte_status_idx ON paliad.projekte (status);
CREATE INDEX projekte_reference_trgm ON paliad.projekte USING GIN (reference gin_trgm_ops);
CREATE INDEX projekte_title_trgm ON paliad.projekte USING GIN (title gin_trgm_ops);
```
**Why ltree and not a recursive CTE?** RLS is called once per candidate row on every SELECT. A recursive CTE per row is O(depth) repeated per predicate call. `path @> ancestor_path` uses the GiST index and collapses to one index scan. This is the biggest performance decision in the doc; ltree is the right tool.
**Why a materialised path *and* `parent_project_id`?** The parent FK is the source of truth for the tree (used by `ON DELETE CASCADE`). The `path` + `depth` columns are derived state maintained by a trigger. Keeping both is redundant on purpose — the FK guarantees referential integrity; the path gives us fast traversal. Updates to `parent_project_id` re-compute path for the subtree in the trigger.
**Tree trigger sketch:**
```sql
CREATE FUNCTION paliad.projekte_sync_path() RETURNS trigger LANGUAGE plpgsql AS $$
DECLARE
parent_path ltree;
BEGIN
IF NEW.parent_project_id IS NULL THEN
NEW.path := text2ltree(replace(NEW.id::text, '-', '_'));
NEW.depth := 0;
ELSE
SELECT path, depth + 1 INTO parent_path, NEW.depth
FROM paliad.projekte
WHERE id = NEW.parent_project_id;
IF parent_path IS NULL THEN
RAISE EXCEPTION 'parent project % not found', NEW.parent_project_id;
END IF;
NEW.path := parent_path || text2ltree(replace(NEW.id::text, '-', '_'));
END IF;
RETURN NEW;
END;
$$;
CREATE TRIGGER projekte_sync_path_ins
BEFORE INSERT ON paliad.projekte
FOR EACH ROW EXECUTE FUNCTION paliad.projekte_sync_path();
-- On parent change, re-path both this row and every descendant.
CREATE FUNCTION paliad.projekte_rewrite_subtree() RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
IF NEW.parent_project_id IS DISTINCT FROM OLD.parent_project_id THEN
PERFORM paliad.projekte_sync_path() FROM paliad.projekte WHERE id = NEW.id;
UPDATE paliad.projekte
SET path = NEW.path || subpath(path, nlevel(OLD.path) - 1),
depth = NEW.depth + (nlevel(path) - nlevel(OLD.path))
WHERE path <@ OLD.path
AND id <> NEW.id;
END IF;
RETURN NEW;
END;
$$;
```
(Sketch — implementer will refine. The constraint that uuid-hyphens aren't valid in ltree labels means we encode UUIDs with `-`→`_`. Alternative: use `hashtext(id::text)::text` to keep labels short — discuss with implementer.)
### 2.3 `paliad.teams`
**Two kinds, one table.** The shape is similar enough that splitting into `dezernate` + `project_teams` would mostly duplicate columns. A `type` column + partial CHECK constraints is cheaper.
```sql
CREATE TABLE paliad.teams (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
type text NOT NULL CHECK (type IN ('dezernat','project_team')),
name text NOT NULL,
-- For type = 'dezernat':
partner_id uuid REFERENCES auth.users(id) ON DELETE SET NULL,
office text CHECK (office IS NULL OR office IN (
'munich','duesseldorf','hamburg',
'amsterdam','london','paris','milan')),
-- For type = 'project_team':
projekt_id uuid REFERENCES paliad.projekte(id) ON DELETE CASCADE,
is_active boolean NOT NULL DEFAULT true,
metadata jsonb NOT NULL DEFAULT '{}',
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
-- Shape invariants per type.
CONSTRAINT teams_dezernat_shape CHECK (
type <> 'dezernat'
OR (partner_id IS NOT NULL AND office IS NOT NULL AND projekt_id IS NULL)
),
CONSTRAINT teams_project_team_shape CHECK (
type <> 'project_team'
OR (projekt_id IS NOT NULL AND partner_id IS NULL AND office IS NULL)
)
);
-- One project_team per Projekt (if any).
CREATE UNIQUE INDEX teams_one_team_per_projekt
ON paliad.teams (projekt_id) WHERE type = 'project_team';
CREATE INDEX teams_partner_idx ON paliad.teams (partner_id) WHERE type = 'dezernat';
CREATE INDEX teams_office_idx ON paliad.teams (office) WHERE type = 'dezernat';
CREATE INDEX teams_projekt_idx ON paliad.teams (projekt_id) WHERE type = 'project_team';
```
**Critique already anticipated.** Mixing two entities in one table is a smell. I accept the smell because: (a) the queries we actually run split cleanly by `type`; (b) the join from a user to "every team I'm on" wants a single table; (c) project teams and dezernate both feed the same `team_mitglieder` roster table and the same per-team role enum overlap is ~80%. If we discover real divergence (project teams grow a `stage` field, dezernate grow a `parent_dezernat_id`), split then.
### 2.4 `paliad.team_mitglieder`
Roster for **both** kinds of team. Dezernat and project-team memberships coexist — a user is typically in exactly one Dezernat *and* on multiple project teams.
```sql
CREATE TABLE paliad.team_mitglieder (
team_id uuid NOT NULL REFERENCES paliad.teams(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
role text NOT NULL CHECK (role IN (
'partner','associate','pa','trainee','of_counsel',
'secretariat','lead','local_counsel','expert','observer'
)),
added_at timestamptz NOT NULL DEFAULT now(),
added_by uuid REFERENCES auth.users(id) ON DELETE SET NULL,
PRIMARY KEY (team_id, user_id)
);
CREATE INDEX team_mitglieder_user_idx ON paliad.team_mitglieder (user_id);
```
Role values overlap intentionally: `partner`, `associate`, `pa`, `trainee`, `of_counsel`, `secretariat` are the typical Dezernat roles; `lead`, `associate`, `pa`, `of_counsel`, `local_counsel`, `expert`, `observer` are the typical project-team roles. The union is finite and small — don't over-engineer with separate role enums per team type.
### 2.5 `paliad.projekt_mitglieder` (replaces `collaborators uuid[]`)
I recommend **flattening project-team rosters into a dedicated junction table** instead of going through `teams` + `team_mitglieder` for the project-team case. Reason: project-team membership is the hot path for RLS. A dedicated two-column junction with a covering index beats any indirection through `teams`.
```sql
CREATE TABLE paliad.projekt_mitglieder (
projekt_id uuid NOT NULL REFERENCES paliad.projekte(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
role text NOT NULL CHECK (role IN (
'lead','associate','pa','of_counsel','local_counsel','expert','observer'
)),
added_at timestamptz NOT NULL DEFAULT now(),
added_by uuid REFERENCES auth.users(id) ON DELETE SET NULL,
PRIMARY KEY (projekt_id, user_id)
);
CREATE INDEX projekt_mitglieder_user_idx ON paliad.projekt_mitglieder (user_id);
```
**So what's `paliad.teams` type='project_team' for?** Two things the junction can't express alone: (a) the *identity* of the team as a first-class object (naming, status, metadata, invitations); (b) a place to attach team-level settings (e.g., a project-team Slack channel URL, a CalDAV group calendar id). If we decide we don't need either, `teams` shrinks to dezernate only and `project_team` rows go away. That's fine too — implementation can start with junction-only and add `teams` rows on demand.
**Opinion:** start with `projekt_mitglieder` only. Add `teams` rows for project teams if/when we ship team-scoped features (project Slack channel, group calendar). For the purposes of visibility and role, the junction table is sufficient.
### 2.6 Child tables — single `project_id` polymorphic FK
No polymorphic magic. Every node in the tree is a `projekte` row. A Frist attached to "the Siemens SEP litigation" just FKs to the litigation-level projekt. A Frist on the root Mandat-level projekt is rare but expressible. Polymorphic multi-FK tables (with multiple nullable parent columns + a CHECK) are a pattern we have today on `notizen`, and they create RLS pain — we avoid extending it.
Revised child tables (columns that change only):
| Table | Today | v2 |
|---|---|---|
| `paliad.parteien` | `akte_id NOT NULL` | `project_id NOT NULL` |
| `paliad.fristen` | `akte_id NOT NULL` | `project_id NOT NULL` |
| `paliad.termine` | `akte_id NULL` | `project_id NULL` (personal stays NULL) |
| `paliad.dokumente` | `akte_id NOT NULL` | `project_id NOT NULL` |
| `paliad.akten_events` | `akte_id NOT NULL` | `project_id NOT NULL` (table stays `akten_events` for history; see §10) |
| `paliad.checklist_instances` | `akte_id NULL` | `project_id NULL` (personal stays NULL) |
| `paliad.notizen` | 4 nullable FKs (akte/frist/termin/event), 1-of CHECK | **Keep as-is** — still polymorphic across frist/termin/event/*project*; `akte_id`→`project_id`. |
`notizen` stays polymorphic because notes attach to three different kinds of entity (Projekt, Frist, Termin, AktenEvent) — a note on a Frist is *not* the same thing as a note on the owning Projekt. The alternative (always attach at Projekt and store `frist_id` / `termin_id` in metadata) loses referential integrity; reject it.
### 2.7 `paliad.users` changes
- **Drop:** `dezernat text` (free-text, only introduced in migration 015).
- **Keep:** `office`, `role`, `practice_group`, `lang`, `email_preferences`.
- **New:** nothing — Dezernat membership moves to `team_mitglieder` with `team_id` pointing at a `teams` row of type `dezernat`.
Migration 015 left `dezernat` as free text precisely because the partner might not have registered yet. v2 keeps the freedom differently: during onboarding, the user either (a) picks an existing Dezernat from a dropdown (fed from `paliad.teams WHERE type='dezernat'`) or (b) types a new one, and the onboarding service auto-creates a `teams` row with `partner_id = NULL` and a note "claim this partnership by signing up with role=partner". The partner claims on their own first-login.
---
## 3. Polymorphic FK strategy (the explicit recommendation)
> **Single `project_id` on all child tables (except `notizen`).**
Rationale:
- Everything a Frist/Termin/Dokument/Partei could "attach to" is now a row in `paliad.projekte`. A Mandant-level Frist FKs to the `project_type='mandat'` root. A verfahren-level Frist FKs to the `project_type='verfahren'` leaf. No discriminator column, no CHECK constraint juggling.
- RLS becomes one predicate: `paliad.can_see_project(project_id)`. Today's `can_see_akte()` + `notiz_is_visible()` split goes away for 6 of 7 child tables.
- Client visibility (a Mandant-level Frist like "send yearly renewal reminder") is uniform: it just lives on the Mandant-level projekt — no `client_id` FK on child tables, no third polymorphic branch.
- Query aggregation across a client's work ("show me all deadlines in the next 30 days for Siemens") is a single JOIN: `fristen JOIN projekte ON fristen.project_id = projekte.id WHERE projekte.path <@ (SELECT path FROM projekte WHERE id = <mandat-projekt-id>)`.
Alternatives I considered and rejected:
- **Multiple nullable FKs (`client_id`, `litigation_id`, `patent_id`, `verfahren_id`) with a 1-of CHECK.** Reproduces the notizen pain for every child table. Harder to index, harder for RLS. Rejected.
- **`parent_type text` + `parent_id uuid` (classic polymorphic)**. Kills foreign-key integrity. Rejected.
- **Separate child tables per level (`mandat_fristen`, `litigation_fristen`, …)**. Absurd proliferation. Rejected on sight.
`notizen` is the one exception because a note genuinely attaches to one of four *kinds of entity*, not to four different positions in the same tree. Keep the 4-FK-one-nullable shape (akte_id → **project_id**, frist_id, termin_id, akten_event_id; CHECK = 1-of-4).
---
## 4. Visibility model
### 4.1 Design principles
1. Visibility is **tree-connected**: if you can see one node, you can see the whole tree (root → all descendants). Mimics how litigation teams actually work.
2. Office-scoping stays **at the project level**, not the Mandant level, because different Projekte under one client may legitimately belong to different offices (e.g., the client's Munich patent prosecution vs. their Düsseldorf enforcement).
3. Project-team membership **grants visibility**, including for users outside `owning_office`.
4. Mandant-level visibility (`mandanten.collaborators`, `mandanten.firm_wide_visible`) grants visibility to the **Mandant** and its **entire project tree**. This is the firm-wide or relationship-partner override.
5. `admin` role sees everything.
### 4.2 The predicate, in English
A user U can see a Projekt P iff **any** of the following:
- `P.firm_wide_visible = true`, **or**
- `P.owning_office = U.office`, **or**
- U is in `projekt_mitglieder` for P, **or**
- U is in `projekt_mitglieder` for **any ancestor or descendant of P** (tree-connected visibility), **or**
- `P.client_id` points to a Mandant M where:
- `M.firm_wide_visible = true`, **or**
- U's uuid ∈ `M.collaborators`, **or**
- `U.role = 'admin'`.
A user U can see a Mandant M iff **any** of:
- `M.firm_wide_visible = true`, **or**
- `M.owning_office = U.office`, **or**
- U's uuid ∈ `M.collaborators`, **or**
- U can see **any** Projekt under M (inductive), **or**
- `U.role = 'admin'`.
### 4.3 SQL predicate
```sql
-- Canonical visibility predicate for projects. Used in RLS and mirrored at
-- the service layer (AkteService.ListVisibleForUser equivalent).
CREATE OR REPLACE FUNCTION paliad.can_see_project(_project_id uuid)
RETURNS boolean
LANGUAGE sql
STABLE
SECURITY DEFINER
SET search_path = paliad, public
AS $$
WITH me AS (
SELECT id, office, role FROM paliad.users WHERE id = auth.uid()
),
tgt AS (
SELECT id, client_id, owning_office, firm_wide_visible, path
FROM paliad.projekte
WHERE id = _project_id
)
SELECT EXISTS (SELECT 1 FROM tgt WHERE tgt.firm_wide_visible)
OR EXISTS (SELECT 1 FROM tgt, me WHERE tgt.owning_office = me.office)
OR EXISTS (SELECT 1 FROM me WHERE me.role = 'admin')
OR EXISTS (
-- membership at target, or at any ancestor/descendant
SELECT 1 FROM paliad.projekt_mitglieder pm, tgt
WHERE pm.user_id = auth.uid()
AND pm.projekt_id IN (
SELECT id FROM paliad.projekte
WHERE path @> tgt.path OR path <@ tgt.path
)
)
OR EXISTS (
SELECT 1 FROM paliad.mandanten m, tgt
WHERE m.id = tgt.client_id
AND (m.firm_wide_visible
OR auth.uid() = ANY (m.collaborators))
);
$$;
```
The `path @> tgt.path OR path <@ tgt.path` clause is the tree-connected check: any project whose path is an ancestor or descendant of the target's path. Uses the GiST index on `projekte.path`.
**Performance note.** For a litigation tree of ~20 nodes with ~100 members, the predicate runs a handful of index probes per row. Measurably worse than today's flat `can_see_akte()` (one EXISTS), but still sub-millisecond in Postgres. If we ever see RLS cost dominate a listing page, the follow-on is to cache "visible project ids for user X" in a session-scoped CTE at the application layer (same trick we use in `ListVisibleForUser`).
### 4.4 Cross-office teams — concretely
Example: Munich partner (Dezernat A) leads; Düsseldorf associate and London local counsel are staffed in.
- The Litigation-level Projekt is created with `owning_office = 'munich'`.
- The Munich partner, the Düsseldorf associate, and the London local counsel all get rows in `projekt_mitglieder` (roles `lead`, `associate`, `local_counsel`).
- Result: the Düsseldorf associate can see the whole litigation tree even though `owning_office <> 'duesseldorf'`. Munich-office colleagues not on the team can still see it (office-scope). London colleagues not on the team cannot see it.
**Edge case: "Chinese-walled" cases.** If a single Akte needs to be hidden from the rest of `owning_office` (conflict of interest), `owning_office` can't carry the day. Add a boolean `restricted` column in a later iteration that flips the predicate to team-only. Don't build now — wait for the first real conflict.
---
## 5. Migration plan
Non-destructive, phased. Data survives at every step.
### Phase 1 — Add new tables (no FK rewrites)
Migration `018_v2_core_tables`:
- `CREATE EXTENSION IF NOT EXISTS ltree;`
- Create `paliad.mandanten`, `paliad.projekte`, `paliad.teams`, `paliad.team_mitglieder`, `paliad.projekt_mitglieder`.
- Create the path trigger.
- No change to `paliad.akten` or its children yet. Old code keeps running.
Acceptance: `\dt paliad.*` shows the new tables. Smoke test: insert a Mandant + one Projekt tree, query via `path @>`.
### Phase 2 — Backfill `paliad.projekte` from `paliad.akten` (synthetic Mandanten)
Migration `019_v2_backfill_projects_from_akten`:
- For each distinct `owning_office` with any Akte, create one synthetic Mandant: `name = 'Unbekannter Mandant (<office>)'`, `status = 'active'`, `owning_office = <office>`, `metadata = {"synthetic": true}`.
- Insert a `paliad.projekte` row for every `paliad.akten` row. **Same UUID** (`projekte.id = akten.id`), `client_id = synthetic mandant of matching office`, `parent_project_id = NULL`, `project_type = 'verfahren'` (best-match to current flat Akte semantics — most are single proceedings), `title`, `reference = aktenzeichen`, `owning_office`, `firm_wide_visible`, `created_by` copied 1:1. The path trigger populates `path` and `depth`.
- Also backfill `projekt_mitglieder` from `paliad.akten.collaborators` (array → rows with `role='associate'`).
Acceptance: `(SELECT COUNT(*) FROM paliad.projekte) = (SELECT COUNT(*) FROM paliad.akten)`; every akten id survives as a projekte id. Visibility-predicate returns the same answers as `can_see_akte` for every (user, akte) pair (spot-check).
### Phase 3 — Rename FK columns on child tables to `project_id`
Migration `020_v2_rename_akte_id_to_project_id`:
- For `parteien`, `fristen`, `termine`, `dokumente`, `akten_events`, `checklist_instances`: `ALTER TABLE … RENAME COLUMN akte_id TO project_id;` and `ALTER TABLE … RENAME CONSTRAINT <akte_fk> TO <project_fk>;` plus rewrite the REFERENCES target from `paliad.akten` to `paliad.projekte`.
- For `notizen`: `RENAME COLUMN akte_id TO project_id;` similarly; keep `frist_id/termin_id/akten_event_id` intact.
- Because of the shared UUID trick in Phase 2, no data moves. Indexes are renamed in the same migration.
Acceptance: `\d paliad.fristen` shows `project_id uuid NOT NULL REFERENCES paliad.projekte(id)`. Existing SELECTs joining to `paliad.akten` now break — that's the signal to cut the application code over in Phase 4.
### Phase 4 — Cut application code over to `paliad.projekte`
- Rename Go types: `models.Akte` → `models.Projekt`. Keep `models.Akte` as a deprecated type alias for one release for external API compatibility if needed.
- `services.AkteService` → `services.ProjektService`. Preserve method signatures; internals switch to `paliad.projekte`.
- Update handlers. `/api/akten` becomes an alias to `/api/projekte` (same handler, same JSON shape during transition — `projekte` additionally exposes `client_id`, `parent_project_id`, `project_type`, `path` fields).
- Update the dashboard query to aggregate by `projekte` (tree-walk already shown in §4.3).
Acceptance: the app runs end-to-end on the new schema; old routes still resolve; old JSON shapes still accepted (new fields additive).
### Phase 5 — New Mandant UI + partner cleanup
- `/mandanten` list + detail pages. Partners assign every synthetic-Mandant project to a real Mandant row (bulk "Change Mandant" on the project-detail page, or a dedicated migration UI at `/einstellungen/migration`).
- After every `projekte.client_id` in `metadata->>'synthetic'=true` has been reassigned, drop the synthetic Mandanten and enforce `paliad.projekte.client_id SET NOT NULL` (migration 021).
Acceptance: no synthetic Mandanten remain. `client_id` is NOT NULL.
### Phase 6 — Decommission `paliad.akten`
- `DROP TABLE paliad.akten` (migration 022). Everything that referenced it has been rewritten.
- Drop the legacy `paliad.can_see_akte()` function; the one-to-one function becomes `can_see_project()`.
Acceptance: `\dt paliad.akten` → not found. All FK constraints still satisfy.
### Rollback
Every migration has a `down`:
- Phases 3 and 6 are destructive DDL (drop column rename → rename back; drop table → re-create). Data preservation in those down-migrations is **not guaranteed** after the migration completes; the safe rollback window is "before Phase 3 runs in production". Document loudly.
- Phases 1, 2, 4, 5 are additive or app-level, rollback by reverting code or running `DELETE FROM paliad.projekte WHERE …`.
---
## 6. RLS policy updates
### 6.1 New policies
`paliad.projekte` — enable RLS. Policies:
```sql
CREATE POLICY projekte_select ON paliad.projekte
FOR SELECT TO authenticated
USING (paliad.can_see_project(id));
-- Non-admins can only create Projekte rooted in an office they belong to
-- (or a tree whose existing parent they can already see).
CREATE POLICY projekte_insert ON paliad.projekte
FOR INSERT TO authenticated
WITH CHECK (
-- Creating under an existing parent? — must already see it.
(parent_project_id IS NOT NULL AND paliad.can_see_project(parent_project_id))
OR
-- Root project: own office, or admin.
(parent_project_id IS NULL
AND (owning_office = (SELECT office FROM paliad.users WHERE id = auth.uid())
OR (SELECT role FROM paliad.users WHERE id = auth.uid()) = 'admin'))
);
CREATE POLICY projekte_update ON paliad.projekte
FOR UPDATE TO authenticated
USING (paliad.can_see_project(id))
WITH CHECK (paliad.can_see_project(id));
-- Delete: partner/admin only. Cascades down the tree.
CREATE POLICY projekte_delete ON paliad.projekte
FOR DELETE TO authenticated
USING (
paliad.can_see_project(id)
AND (SELECT role FROM paliad.users WHERE id = auth.uid()) IN ('partner','admin')
);
```
`paliad.mandanten` — enable RLS. Visibility: any user who can see at least one of the Mandant's Projekte, or who is in `collaborators`, or `firm_wide_visible`, or admin.
```sql
CREATE OR REPLACE FUNCTION paliad.can_see_mandant(_mandant_id uuid)
RETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER
SET search_path = paliad, public AS $$
SELECT EXISTS (
SELECT 1 FROM paliad.mandanten m, paliad.users u
WHERE m.id = _mandant_id
AND u.id = auth.uid()
AND (
m.firm_wide_visible
OR m.owning_office = u.office
OR auth.uid() = ANY (m.collaborators)
OR u.role = 'admin'
OR EXISTS (
SELECT 1 FROM paliad.projekte p
WHERE p.client_id = _mandant_id
AND paliad.can_see_project(p.id)
)
)
);
$$;
CREATE POLICY mandanten_select ON paliad.mandanten
FOR SELECT TO authenticated
USING (paliad.can_see_mandant(id));
CREATE POLICY mandanten_insert ON paliad.mandanten
FOR INSERT TO authenticated
WITH CHECK (
owning_office = (SELECT office FROM paliad.users WHERE id = auth.uid())
OR (SELECT role FROM paliad.users WHERE id = auth.uid()) = 'admin'
);
-- Update/Delete policies analogous; delete is partner/admin-gated.
```
### 6.2 Child-table policies — converge on `can_see_project`
Every child table's policy changes from `paliad.can_see_akte(akte_id)` to `paliad.can_see_project(project_id)`. `notizen` loses its dedicated `notiz_is_visible()` helper in favour of an inline check that dispatches by which FK is set:
```sql
CREATE POLICY notizen_all ON paliad.notizen
FOR ALL TO authenticated
USING (
CASE
WHEN project_id IS NOT NULL THEN paliad.can_see_project(project_id)
WHEN frist_id IS NOT NULL THEN paliad.can_see_project(
(SELECT project_id FROM paliad.fristen WHERE id = frist_id))
WHEN termin_id IS NOT NULL THEN
CASE
WHEN (SELECT project_id FROM paliad.termine WHERE id = termin_id) IS NULL
THEN (SELECT created_by FROM paliad.termine WHERE id = termin_id) = auth.uid()
ELSE paliad.can_see_project(
(SELECT project_id FROM paliad.termine WHERE id = termin_id))
END
WHEN akten_event_id IS NOT NULL THEN paliad.can_see_project(
(SELECT project_id FROM paliad.akten_events WHERE id = akten_event_id))
ELSE false
END
)
WITH CHECK (...same...);
```
(We may extract a helper `notiz_is_visible(project_id, frist_id, termin_id, akten_event_id)` again — symmetric to today's.)
### 6.3 Admin bootstrap
Unchanged. The `pg_advisory_xact_lock(7346298141)` onboarding gate that lets the first user self-assign `role='admin'` still works. Nothing to do.
### 6.4 Defense-in-depth at the service layer
Same pattern as today: every service mirrors the predicate in `ListVisibleForUser` for indexed performance. The SQL is wordier for the tree variant — we do it once in `ProjektService.listVisibleIDsForUser` (returns a `map[uuid.UUID]struct{}`) and re-use across list endpoints.
---
## 7. API surface changes
### 7.1 New endpoints
| Method + path | Purpose |
|---|---|
| `GET /api/mandanten` | List Mandanten the user can see. |
| `POST /api/mandanten` | Create Mandant. |
| `GET /api/mandanten/{id}` | Detail. |
| `PATCH /api/mandanten/{id}` | Update. |
| `DELETE /api/mandanten/{id}` | Delete (partner/admin only). |
| `GET /api/mandanten/{id}/projekte` | List root-level Projekte under this Mandant. |
| `GET /api/projekte` | List top-level visible Projekte (flat root list). |
| `POST /api/projekte` | Create a Projekt (optionally nested via `parent_project_id`). |
| `GET /api/projekte/{id}` | Detail + immediate children. |
| `GET /api/projekte/{id}/tree` | Full subtree (depth-first). |
| `PATCH /api/projekte/{id}` | Update. |
| `DELETE /api/projekte/{id}` | Cascade delete subtree (partner/admin). |
| `GET /api/projekte/{id}/kinder` | Direct children (for lazy-loaded UI). |
| `POST /api/projekte/{id}/team` | Add project team member. |
| `DELETE /api/projekte/{id}/team/{user_id}` | Remove member. |
| `GET /api/teams` | List Dezernate (+ optionally project teams). |
| `POST /api/teams` | Create Dezernat (admin-gated). |
| `GET /api/teams/{id}/mitglieder` | List members. |
### 7.2 Aliased endpoints
During transition:
- `GET /api/akten` → alias of `GET /api/projekte?project_type=verfahren` (or all, with `akte_type`/`court` fields surfaced) for clients still using the old shape.
- `POST /api/akten` → alias of `POST /api/projekte` with `project_type='verfahren'` default.
- `/api/akten/{id}/fristen` → alias of `/api/projekte/{id}/fristen`.
Remove aliases after 60 days + 1 green deployment.
### 7.3 Retired endpoints
None immediately. Keeping aliases means no 404s for the UI during the Phase 4 cutover.
### 7.4 New query parameters
- `?client_id=<uuid>` on `GET /api/projekte` — scope to one Mandant's tree.
- `?project_type=<type>` — filter by type.
- `?ancestor=<uuid>` — subtree of a given root (uses `path <@`).
- `?include_children=true` on `GET /api/projekte/{id}` — one-shot detail + subtree (cheap because of the path index).
---
## 8. UI implications
### 8.1 Sidebar
Insert "Mandanten" above "Akten" in the "ARBEIT" group. Rename "Akten" → "Projekte" in a second phase once partners get used to the concept — initially, keep "Akten" as the label and add the Mandanten entry only.
```
— ARBEIT —
Dashboard
Mandanten ← NEW
Projekte ← renamed from "Akten" (phase 2)
Fristen
Termine
```
### 8.2 New pages
- `/mandanten` — list. Columns: Name, Büro, #Projekte, #aktive Fristen, letzte Aktivität.
- `/mandanten/neu` — create form.
- `/mandanten/{id}` — detail with tabs: Übersicht, Projekte (the tree at this root), Fristen (aggregated), Termine (aggregated), Notizen (aggregated), Team (aggregated from all child projekt_mitglieder).
- `/projekte` — flat list of root projects + filter by Mandant, type, office.
- `/projekte/{id}` — detail. Tabs today (`verlauf`, `parteien`, `fristen`, `termine`, `dokumente`, `notizen`, `checklisten`) stay. **New first tab: "Untergeordnet"** — renders the subtree of child projekte as a collapsible list. A "Neues Untervorhaben" button under each node creates a child.
- `/projekte/neu` — create. Form adapts to `project_type`: `mandat`/`litigation`/`patent` surface no `court` / `court_ref`; `verfahren` does.
### 8.3 Detail-page tree rendering
On `/projekte/{id}` the sidebar (left sub-nav) renders the ancestor path (breadcrumbs: Mandant → Litigation → Patent → Verfahren). Children render in the Untergeordnet tab as a collapsible tree. Keep click-depth low: clicking a child navigates to that child's detail page; siblings render as flat siblings on the current page.
### 8.4 Team editor
On `/projekte/{id}` under the Team tab: list of team members with role, "Mitglied hinzufügen" modal with autocomplete fed by `GET /api/users`. Removing the `collaborators uuid[]` array means the multi-pick UI gets a proper role column and an "added_by/at" audit line, which today's model can't show.
### 8.5 Dashboard impact
Dashboard queries aggregate across **every** Projekt the user can see (all tree levels). Fristen summary widget: `SELECT * FROM paliad.fristen f JOIN paliad.projekte p ON f.project_id = p.id WHERE can_see_project(p.id) AND f.status='pending' AND f.due_date <= now() + interval '30 days'`. Same tree-agnostic pattern for Termine.
"Neu auf ..." — add a Mandanten-level aggregate: "Siemens AG: 3 neue Fristen diese Woche, 1 Verhandlung am Donnerstag". Requires a `client_id` join via `projekte` — same index pattern.
### 8.6 Fristenrechner "Save to Akte"
Rename button to "Zur Verfahren-Akte speichern" (or simpler: "Zur Akte speichern" still works because Verfahren are the most common target). The target picker is now a two-step autocomplete: Mandant → Projekt (scoped to that Mandant's tree). Or skip Mandant picker entirely and autocomplete across all visible projekte — simpler, lets the user jump straight to the right leaf by typing the court-ref.
### 8.7 Checklisten Akten-link
Minimal change: `akte_id` → `project_id` on the service layer and UI picker. Picker is the same cross-tree autocomplete.
### 8.8 CalDAV sync
No material change. Today each Termin's iCal includes the Akte's `aktenzeichen` in the DESCRIPTION. v2 includes the full path: `Siemens AG · Siemens v. Huawei · EP 1 234 567 · UPC_CFI_123/2026`. Lawyers will find events in their calendar far more easily.
---
## 9. Impact on existing features
| Feature | Change |
|---|---|
| Dashboard | Queries shift from `akten` to `projekte`; widgets aggregate tree-wide. Mandanten-level "Neu auf ..." widget added. |
| Fristenrechner | Save-to-Projekt instead of save-to-Akte. Autocomplete is cross-tree (all visible projekte). |
| Fristen list | Columns show `Mandant · Projekt` chain instead of flat Aktenzeichen. Filter by Mandant. |
| Termine list | Same. |
| Notizen | FK rename only (akte_id → project_id). Polymorphic shape preserved. |
| Checklisten | FK rename only. Picker widened to cross-tree autocomplete. |
| CalDAV | Richer DESCRIPTION (full path). Termin ↔ calendar event mapping unchanged. |
| Akten detail page | Gains Untergeordnet tab + tree sub-nav. Existing tabs keep working. |
| Audit trail (Verlauf) | `akten_events` stays as a table name (history); `akte_id` → `project_id`. New event types: `projekt_nested`, `projekt_reparented`, `mandant_assigned`, `team_member_added`, `team_member_removed`. |
| Dokumente (placeholder) | No change today (still placeholder). Future implementation attaches to the right level of the tree. |
---
## 10. Naming conventions — German, with one English holdover
**Decision: German throughout. Match everything shipped so far.**
| Concept | DB table | Go struct | Go service | URL | German UI |
|---|---|---|---|---|---|
| Client | `paliad.mandanten` | `Mandant` | `MandantService` | `/mandanten` | "Mandant" / "Mandanten" |
| Project (generic) | `paliad.projekte` | `Projekt` | `ProjektService` | `/projekte` | "Projekt" / "Projekte" |
| Project sub-type "Mandat" | (row in projekte) | — | — | (row variant) | "Mandat" (Gesamtbeziehung) |
| Project sub-type "Litigation" | (row in projekte) | — | — | (row variant) | "Streitsache" |
| Project sub-type "Patent" | (row in projekte) | — | — | (row variant) | "Patent" |
| Project sub-type "Verfahren" | (row in projekte) | — | — | (row variant) | "Verfahren" |
| Project sub-type "Projekt" | (row in projekte) | — | — | (row variant) | "Projekt" (generisch) |
| Team (structural / project) | `paliad.teams` | `Team` | `TeamService` | `/teams` (admin) | "Team" / "Teams" |
| Team member | `paliad.team_mitglieder` | `TeamMitglied` | — | (sub) | "Teammitglied" |
| Project roster | `paliad.projekt_mitglieder` | `ProjektMitglied` | — | (sub of Projekt) | "Projektmitglied" |
| Party | `paliad.parteien` | `Partei` | `ParteienService` | (sub of Projekt) | "Partei" / "Parteien" |
| Deadline | `paliad.fristen` | `Frist` | `FristService` | `/fristen` | "Frist" / "Fristen" |
| Appointment | `paliad.termine` | `Termin` | `TerminService` | `/termine` | "Termin" / "Termine" |
| Document | `paliad.dokumente` | `Dokument` | `DokumentService` | (sub) | "Dokument" |
| Audit event | `paliad.akten_events` | `AkteEvent` | (in `ProjektService`) | n/a | "Verlauf" |
| Note | `paliad.notizen` | `Notiz` | `NotizService` | cross-cutting | "Notiz" / "Notizen" |
| User | `paliad.users` | `User` | `UserService` | n/a | n/a |
**The one English holdover:** `paliad.akten_events` table name. Rationale:
- It's the audit-trail table name already shipped.
- "Verlauf" is the UI label; the table name is invisible to users.
- Migrating to `projekt_events` would churn migration history for no gain, and any historical tools (Grafana, ad-hoc SQL) keep working. Preserve the name; update the comment and the Go struct semantics.
**Why not `projekt_*` everywhere?**
- `projekt_mitglieder` reads cleanly; kept.
- `projekt_events` would be clean too but see above — churn:benefit ratio unfavourable.
**URL aliases.** `/akten` and `/akten/{id}` keep redirecting to `/projekte` and `/projekte/{id}` indefinitely (bookmark preservation). No hard break. 301 from `/akten/neu` → `/projekte/neu`.
---
## 11. Open questions & deferrable decisions
1. **Patent registry.** Should `external_ref` on a `patent`-type projekt be a FK to a firm-wide `paliad.patente` table (EP number + metadata, shared across Mandanten)? Not today — a single litigation's view of a patent is legitimately separate from the firm-wide "patents we've ever seen" list. Revisit when HLC asks for firm-wide IP inventory. If/when built, add `patent_registry_id uuid` on `projekte` where `project_type='patent'`.
2. **Conflict of interest / Chinese walls.** Partner-level override to restrict a single project to its team roster only (strip office-scope). Not built now; add `restricted boolean` in a follow-on migration, and extend the predicate to skip the office-scope branch when `restricted = true`.
3. **Practice-group scoping.** `paliad.users.practice_group` is already free-text. If HLC splits Patents Litigation vs. Patents Prosecution and wants wall-like isolation, add `visible_to_groups text[]` on `projekte` + predicate extension. Not now.
4. **Matrix management.** A user belongs to one Dezernat (structural) today. If partners share associates (e.g., a "tax-patent" associate is on both the Patents and the Tax Dezernate), relax `team_mitglieder` — it already allows multiple memberships. The onboarding UI currently picks one Dezernat; relax when needed.
5. **Billing hooks.** `mandanten.billing_reference` is provisioned but not wired. Deliberate: HLC has firm-wide billing; Paliad does not compete. Field exists so the UI can show it and the future Outlook/Exchange integration can look it up.
6. **External collaborators.** A Milan boutique working on a case today would go into `projekt_mitglieder` only if they have Supabase accounts. Building external-party access (email-only, scoped, audit-logged) is a post-foundation feature; deferred.
7. **Hard delete vs. archive.** `status='archived'` on Mandanten and Projekte exists; hard-delete is cascade via FK. Consider a `archived_at` + soft-delete semantics once we have retention-policy rules. Not now.
8. **ltree label encoding.** UUIDs with hyphens aren't valid ltree labels. Replace `-` with `_`, or hash. Implementer's call; both work, hash is shorter but loses traceability.
---
## 12. Trade-off summary (for the head)
| Choice | Alternative | Why I picked this | Cost |
|---|---|---|---|
| Single `projekte` tree with type enum | Separate tables per type (mandate/litigation/patent/case) | Polymorphic FK pain, cross-tree queries, UI shared components | `project_type` CHECK has to grow carefully |
| ltree materialised path | Recursive CTE | RLS is the hottest call site; O(log n) tree queries matter | Extension dependency; label encoding quirk |
| Single `project_id` on child tables | Multi-level polymorphic FKs | RLS simplicity, uniform service code | Discipline: every Fristen/Termin has a Projekt, even "client-level" rare cases |
| `mandanten` as a separate table | Project with `type='mandat'` as the conceptual client | Clients have no deadlines/termine/parteien; they're a different shape. Also: Mandant outlives any specific matter. | One extra table |
| `teams` shared between Dezernat + project_team | Two separate tables | Single roster table (`team_mitglieder`), UI/service reuse | Partial CHECK constraints are a minor smell |
| `projekt_mitglieder` junction in addition to `teams` | Route project-team membership through `teams` | Hot path for RLS wants a dedicated two-column junction | Small duplication of concept |
| German naming | Mixed EN/DE | Continuity with everything shipped; audience speaks German | German plural forms (`mandanten`, `projekte`) in URLs |
| Tree-connected visibility | Downward-only (seeing ancestor grants ancestor+descendants only) | Matches how associate-on-one-case actually needs parent context | Slightly bigger RLS query |
| Phased non-destructive migration with preserved UUIDs | Dump-transform-reload | Zero downtime; every child-table row survives untouched | Requires discipline: match UUIDs in the backfill exactly |
---
## 13. Who implements?
Recommendation: **I (cronus) can implement the foundation** — migrations 018–022, the predicate function, the new `ProjektService`, and the API alias shim. Reasons:
- I wrote the design; I know the edge cases.
- The schema work is security-critical (RLS policy + path trigger); having design-context on the implementer cuts review cycles.
- The pragmatic split: cronus does schema + services + aliases + RLS (Phase 1–4). A parallel coder worker does the Mandanten UI (`/mandanten` list + detail + create + partner cleanup wizard) in Phase 5. Cronus does Phase 6 decommission.
If the head prefers to keep cronus on design duty and hand implementation to a coder, the design is detailed enough to hand off — every schema has columns, constraints, triggers, RLS snippets, and migration acceptance criteria. I'd still want to review the RLS + path trigger PR before merge.
---
## 14. Acceptance criteria for the design itself
A "yes" on this design means head agrees to:
- [ ] Mandanten as a first-class table (not just a Projekt type).
- [ ] Single `projekte` tree with 5-value type enum.
- [ ] ltree materialised path + GiST index.
- [ ] Single `project_id` FK on fristen/termine/dokumente/parteien/akten_events/checklist_instances; `notizen` keeps its polymorphic shape with `akte_id` renamed to `project_id`.
- [ ] Tree-connected visibility predicate (ancestors + descendants both reachable from any team node).
- [ ] `paliad.teams` as a single table for Dezernat + project-team, with the two-kind shape CHECK.
- [ ] `projekt_mitglieder` as a hot-path junction, *and* optional `teams` rows of type `project_team` for team-level features.
- [ ] Phased migration with preserved UUIDs between `akten` and `projekte` rows.
- [ ] German naming throughout; `akten_events` table name preserved for continuity.
- [ ] `/akten` URLs alias to `/projekte` indefinitely.