Skip to content

ADR: Community Directory Refactor (2026-01)

Status: Proposed / Under Review Context: Major refactor of the Directory module to transform it from a flat profile list into the authoritative Community Directory pivot point for the platform.

1. Scope & Objectives

The Community Directory is the "Source of Truth" for all identities and relationships within Singular Dream.
Goals: - Implement a 3-perspective pivot model: People, Assets, and Services. - Enforce a hard-coded, stable taxonomy for Personas and Operational Departments. - Standardize Unit identifiers and Floor structures specific to the SD complex. - Integrate billing responsibility and lock-off mode awareness.

2. Conceptual Model (The Identity Pivot)

The Directory is modeled as a Graph where Identities (People/Legal Persons) are connected to Assets (Units/PPE) via Personas (Roles/Contexts).

A. Identity Types

  • Individual: A natural person.
  • Legal Person: A company, trust, or entity.
  • Proxy/Representative: Explicit "acts on behalf of" relationships between Individuals and Legal Persons.

B. Asset Decomposition (The Operational Graph)

Assets in the Directory are decomposed following the Property, Plant, and Equipment (PP&E) taxonomic standard, plus Inventory. This ensures forensic alignment with the Financial System of Record (Capital vs. Expense): - Property (Real Estate): Deeded Units (Residential, Commercial, Storage, Parking). - Plant: Fixed infrastructure requiring lifecycle maintenance (e.g., HVAC units, Elevators, Cisterns). - Equipment: Movable assets with individual serial numbers (e.g., Gym equipment, Security cameras, Staff vehicles). - Inventory (CapEx Spares): Strategic supplies or replacement parts held in stock for PP&E maintenance.

C. Persona Taxonomy (Hard-coded)

Category Subtypes
Owners primary_owner, co_owner, beneficiary_owner, family_non_deed
Residents resident_owner, long_term_renter, short_term_guest
Staff building_administrator, employee, contractor
Operations maintenance, cleaning, front_desk_hospitality, concessions
Governance president, vice_president, treasurer, member_at_large, vigilance_committee_member, vigilance_chief
Admin building_admin (Access/Onboarding), system_admin (Structure/RBAC)
Vendors building_vendor, unit_support_vendor, legal_services, notary, other_professional_services

3. Data Model Design (Firestore)

Collection: people

  • id: Canonical ID.
  • type: individual | legal_person.
  • responsibleIndividualId: ID of the human representative for legal persons.
  • privacyTier: Integer (0-3) governing data redaction.
  • relationships: Array of { relatedId: string, type: 'proxy' | 'beneficiary' | 'representative', effectiveDates: { start, end } }.
  • personas: Array of persona objects (Hat, Subtype, Status, Capabilities).

Collection: units

  • identifier: SD-{Building}-{Floor}{UnitNumber}{OptionalLockoff} (Canonical string).
  • building: A | B | C.
  • floor: E, 0, 1, 2, 3, 4, 5, R.
  • unitNumber: 01..20.
  • lockoffMode: joined | split.
  • lockoffSuffix: A..Z (Optional).
  • billingResponsibility: Array of { identityId: string, priority: number, percentage: number, effectiveDates }.

Integration Hub

  • Property: Linkage to PPE/Assets. Assets reference people IDs.
  • Finance: Receivables reference Directory identities for billing.
  • Operations master: Staff/Employee attributes linked to Directory profiles.

4. UI Architecture & Pivot Modes

A "Golden Workbench" interface with three primary lenses:

  1. People-centric: Discover and manage "Who is who".
  2. Asset-centric: Discover and manage "What is where".
  3. Service-centric: Discover and manage "Who does what".

View Catalog

Each lens provides filtered "Saved Views": - Owners View: Filtered by Owners personas (subtype filters available). - Operations View: Filtered by Staff/Vendor personas (department filters available). - Governance View: Filtered by Board/Committee personas.

5. Security & Privacy Model

  • Privacy Rules: Firestore-level rules enforcing visibility (e.g., Individual email only visible to authorized Building Admin or related Owners).
  • Persona Escalation: Logic to prevent unauthorized assignment of "Admin" or "Governance" personas.
  • Audit Trails: Every mutation recorded with { actorId, timestamp, oldVal, newVal }.

6. Gap Analysis

Feature Current State Target State Gap / Change Required
Identity Types Flat DirectoryProfile. Individual vs Legal Person root. Add type field; refactor profile structure.
Persona Taxonomy Mixed roles/types. Hard-coded hierarchical taxonomy. Migrate existing roles to new Persona sub-objects.
Admin Subtypes Single admin role. building_admin vs system_admin. Split responsibilities; update UI badges and rules.
Unit Naming Varied strings. Strict SD-X-00Y format. Implement normalization engine; migrate data.
Floor Codes Numeric. Button codes (E, 0-5, R). Update storage and UI display logic.
Lock-off Simple boolean. Mode-based (Joined/Split). Add lockoffMode and effective attribute logic.
Billing Linked to "Owner". Multi-party billing responsibility. Store billing priority separate from deed ownership.
Services Basic Vendor list. Service-centric pivot. Link vendors to assets and scope.
Security Basic role gates. Granular Persona/Privacy rules. Rewrite Firestore rules for persona-based access.

7. Migration & Search Plan

Migration Sequence

  1. Scaffolding: Create new schema fields/collections.
  2. Shadow Writing: Update server actions to write to both old and new fields.
  3. Backfill: Scripted migration of existing profiles/units to the new taxonomy.
  4. Read Switch: Update UI to consume the new model.
  5. Deprecation: Remove legacy fields after stability check.

Search Strategy

  • Keywords Indexing: Maintain a keywords array on profiles/units.
  • Bounded Queries: Use Firestore composite indexes for subtype + status filters.

8. Integration Impact Matrix

Module Impact
Governance Voting weights must now look at "Owner" personas and deed weights.
Finance Billing must target "Billing Responsible" party identified in Directory.
Operations Service Dispatch must look up Vendors via Service-centric Directory lens.
Property Entry Management/Keys must respect "Resident" persona effective dates.
Auth Login logic needs to resolve identity and active personas for the hat-switcher.

10. Architectural Refinements (Antigravity Suggestions)

  • Computed Attributes: All unit attribute math (bedrooms, bathrooms, indiviso) SHALL be computed via the unit-helper.ts based on current lockoffMode.
  • Persona Lifecycle: Personas SHALL support states draft, active, and historic to facilitate multi-step onboarding and auditability.
  • Forensic Linkage: Relationships (Deeds, Leases, Proxies) SHALL maintain a sourceDocumentId referencing the authoritative file or ledger entry.
  • Privacy Tiers: Implement a privacyTier field (0-3) to automate data redaction for non-admin observers.
  • Asset Evolutionary Preparedness: The schema SHALL support generalization of Assets beyond "Units". This includes enums for ASSET_CATEGORY (Property, Plant, Equipment, Inventory) and explicit linkage to Financial Asset Tags (G/L classification).