Skip to content

System Design: Unified Identity & Governance

Status: DRAFT Version: 1.13.0 (Moved to Unified Layer) Domain: Unified / Identity

1. Executive Summary

This Identity System serves as the Nexus of the Singular Dream ecosystem, associating People to Property and allowing us to define the many complex relationships that govern community life.

It moves beyond simple user accounts to model the reality of the various Personas (or "hats") that individuals wear. By accurately modeling this web of interactions, the system provides a powerful foundation for the traceability and Sovereignty of all actions and decisions.

Crucially, this system is a Transactional Compliance Engine.
The rigorous identification requirements—collecting formal copies of Deeds, IDs, and Leases—are not bureaucratic friction; they are functional necessities. This verified data enables the system to facilitate real-world transactions: providing evidentiary support for Notarial Acts, administrative functions with Banks, compliance with Tax Authorities, and validation for Real Estate Agents.

Democratizing Governance By automating the verification of identity and authority, this system assists in automating notarial activity and facilitates seamless participation in governance. It liberates owners from the need to attend meetings in person or navigate onerous manual procedures. Instead, we can meet, decide, and tally votes immediately and electronically—making life easier for everyone and taking decision-making out of the shadows and into the modern era of democratic participation.

2. Core Concepts

2.1 The Identity Graph (Enhanced)

The system decouples Authentication from Identity.

  • Authentication (UserCred): A specific login method (Email A, Email B, Phone).
  • Identity (The Human/Entity): The single "Source of Truth" record.
  • Persona (The Hat): Contextual roles.

Critical Rule: One Identity can have Many Authentications.

  • Example: Michael logs in with mwhiggins@mac.com AND admin@singulardream.org. Both resolve to the SAME Identity: Michael Higgins.
graph TD
    subgraph "Authentication Methods"
        Email1(["Auth: mwhiggins@mac.com"])
        Email2(["Auth: admin@singulardream.org"])
        Phone1(["Auth: +1 555-0199"])
    end

    Email1 -->|Resolves To| Human["Identity: Michael Higgins"]
    Email2 -->|Resolves To| Human
    Phone1 -->|Resolves To| Human

    subgraph "The Personas (Hats)"
        Human -->|Has| Owner["Persona: Owner Unit 402"]
        Human -->|Has| Board["Persona: Board Treasurer"]
        Human -->|Has| Proxy["Persona: Proxy for Higgins LLC"]
        Human -->|Has| Guest["Persona: Guest Unit 302 (Dec 1-5)"]
    end

2.2 The Secure Vault (Transactional Grade)

A specialized storage domain for high-sensitivity documents (Deeds, Government IDs, Leases).

  • Purpose: To support rigorous external transactions (Banking, Taxes, Notary).
  • Isolation: Files are stored in a restricted Firebase Storage bucket (vault-secure).
  • Access Control: Strictly ABAC. Only the System and Admin (with Audit) can view.

3. Workflow Design

3.1 The "Claim-to-Grant" Lifecycle

sequenceDiagram
    participant User
    participant Wizard as Access Wizard
    participant Vault as Secure Vault
    participant Admin as Admin Queue
    participant System as Automation

    User->>Wizard: 1. "I am an Owner of Unit 402"
    User->>Wizard: 2. Uploads Deed.pdf
    Wizard->>Vault: 3. Encrypt & Store
    Wizard->>Admin: 4. Create AccessRequest (Pending)

    Note over Admin: Admin reviews Request + Deed

    Admin->>System: 5. Click "APPROVE"

    System->>System: 6. Identity Resolution
    Note right of System: Checks if Human exists.<br/>If yes, links Auth.<br/>If no, creates Human.

    System->>System: 7. Create Ownership Record
    System->>User: 8. Grant Role & Notify

3.2 Guest Lifecycle (Time-Bound Access)

Requirement: Guests need access ONLY during their reservation, but must pay bills before/after.

Lifecycle States:

  1. Pre-Arrival (Booked): Access to "Concierge" & "Pre-Checkin" only.
  2. Active (Check-in -> Check-out): FULL ACCESS. Amenities, Door Unlock, Services.
  3. Historical (Post-Stay): Access restricted to "Billing" & "History" only.

Automation Logic:

  • The Persona has effectiveDates: { start, end }.
  • A nightly job (Scheduler) checks effectiveDates and toggles the Active status.
  • Financial Capability: The Guest Persona creates a sub-ledger (House Account) allowing them to accrue fines/charges even if standard access is revoked.

4. Persona Scenario Matrix

Identity scenarios are categorized by the Primary Relationship to the Community.

Category A: Owners & Residents

ID Persona Description & Requirement
A1 Standard Owner Individual on Deed. Full Rights.
A2 Multi-Unit Owner Individual owning >1 Unit. Needs unified dashboard viewing all units.
A3 Corporate Owner (LLC) Legal Entity on Deed. Requires a linked Proxy (Human) to act.
A4 Immediate Family Spouse or Child of Owner. Usually resides in unit. Rights derived from Owner.
A5 Extended Family Sibling, Parent, or Cousin of Owner. Very common regional use-case. May require specific configuration for access rights (Full vs Guest-like).
A6 Tenant (Long-Term) Leaseholder (>30 days). Requires Lease Evidence. Rights limited by Owner settings.
A7 Guest (Commercial) Hotel/Airbnb (<30 days). Paying Customer. Time-Bound.
A8 Friend (Non-Commercial) Authorized Visitor of Owner. No commercial agreement. Time-Bound (or Open-Ended).

Category B: Staff & Management

ID Persona Description & Requirement
B1 HOA Staff Employed by the Association (e.g., Front Desk, Security). Access to Building Systems.
B2 Admin Staff Property Management Company employees (e.g., General Manager, Accountant). Broad Admin Access.
B3 Private Staff Employed by an Owner (e.g., Nanny, Chef, Driver). Access limited to specific Unit + Common Areas.
B4 Vendor Technician Employed by a Vendor (Category C1). Access is Work-Order bound (Fixing things).
B5 Concession Staff Employed by a Concessionaire (Category C5). Access is Order-Fulfillment bound (Serving things).
B6 Partner Staff Employed by a Service Partner (Category C6). Access is Service-Delivery bound (e.g., Laundry drop-off).

Category C: Service Providers & External

ID Persona Description & Requirement
C1 Vendor Entity Maintenance/Repair Company (e.g., "Bob's AC"). Holds Insurance/Contracts. Payments for repairs.
C2 Agent / Realtor 3rd Party selling/leasing a unit. Access limited to Showing Hours.
C3 Board Member Elected Official. Super-Persona on top of Owner. Access to Decision Governance.
C4 Emergency Services Police/Fire. Override Access (Break-glass protocols).
C5 Concessionaire Amenity Operator (e.g., "The Spa Group"). Contract-Bound (Leasing Space). Employees need POS.
C6 Service Partner Service Provider (e.g., "City Laundry", "Uber Eats"). Contract-Bound (Service Agmt). Employees need seamless entry.

5. Data Model Impact

5.1 Identity Schema Updates

interface Identity {
  id: string;
  type: "individual" | "legal_person";
  displayName: string;
  // NEW: Resolution Links
  linkedProviders: string[]; // Array of Auth UIDs that map to this person
  emailAliases: string[]; // Historical emails known to this person
  primaryEmail: string;
  // ... existing fields
}

5.2 Access Request Schema

interface AccessRequest {
  id: string;
  sourceUid: string; // The Google User Requesting
  requestedPersona: {
    type: "owner" | "tenant" | "agent";
    entityId: string; // e.g., 'unit-402'
    onBehalfOf?: string; // If acting as Proxy for 'Higgins LLC'
  };
  evidence: {
    vaultRecordId: string;
    type: "deed" | "lease" | "id_card";
  }[];
  // ... existing fields
}

7. The Unified Nexus: Hub & Spoke Integrations

To ensure "Identity Sovereignty" and prevent "Shadow Identities" (hidden user lists in other modules), Unified Identity acts as the Hub. All other modules (Spokes) must reference IdentityId or PersonaId—they strictly cannot own their own user records.

graph TD
    classDef hub fill:#f9f,stroke:#333,stroke-width:4px;
    classDef spoke fill:#fff,stroke:#333,stroke-width:1px;

    Identity(Unified Identity<br/>The Sovereign Nexus):::hub

    subgraph "The Spokes (Consumers)"
        Finance(Finance Module)
        Ops(Operations Module)
        Comm(Community Module)
        Audit(Audit Module)
        Access(Physical Access)
        Workflow(Workflow Module)
    end

    Finance -->| bills to | Persona(Persona ID)
    Ops -->| assigned to | Persona
    Comm -->| defines | Persona
    Audit -->| tracks | Identity(Identity ID)
    Access -->| grants | Identity
    Workflow -->| routed to | Persona

    Identity -->| provides | Persona

7.1 Integration Matrix

Target Module Relationship & "Shadow Risk" Mitigation Integration Point
Community Defines residency. Shadow Risk: Community maintaining its own "Resident List". Community consumes Unified Identity to resolve "Who lives here". Ownership records point to IdentityId.
Finance Bills the Persona. Shadow Risk: Finance creating "Customer Accounts" disconnected from Residents. Ledger is owned by PersonaId (e.g. owner_unit_402). Wallet is owned by IdentityId (The Human paying).
Operations Assigns work. Shadow Risk: "Vendor Lists" in Ops that don't map to real identities. Work Orders (WO) are requested by PersonaId and assigned to PersonaId (Staff/Vendor). No free-text names.
Unified Vault Verifies the Claim. Shadow Risk: Documents stored without attribution. Vault Records (Deeds) are uploaded by IdentityId and linked to AccessRequest.
Unified Audit Tracks the Human. Shadow Risk: Logs showing "Admin" without knowing which Admin. All logs strictly reference IdentityId (The Actor), ensuring legal non-repudiation.
Physical Access Grants entry. Shadow Risk: Keycard systems with their own unmapped database. The Access Control Service queries Identity to check profileStatus before opening doors.
Workflow Routes decisions. Shadow Risk: Approval chains hardcoded to emails. Approvals routed to Logic Roles (e.g. "Board Treasurer"), which resolve dynamically to the current PersonaId.

Version History

Version Date Author Change
0.1.0 2026-01-29 Antigravity Initial Audit & Metadata Injection