0002: Application catalog and memberships

• ID: PRD-0002
• Status: Accepted
• Decision maker: Trevor Gerhardt
• Scope: Concourse administration and organization Apps tab, Services, API, SDK, Auth, and Persistence
• Product owner: Trevor Gerhardt
• Design owner: Trevor Gerhardt
• Engineering owner: Trevor Gerhardt
• Last reviewed: 2026-09-25
• Related issues or projects: N/A; the owner requested implementation of the agreed plan directly.
• Related designs: N/A; use existing administration forms and Application cards.
• Related ADRs: Services ownership
• Related user documentation: Concourse application

Summary

Give system administrators one application catalog and explicit organization membership controls. Members see their organization's assigned active applications and intended access modes.

User problem and evidence

The owner requested a model for Midot today and multiple applications later. The planning interview settled names, lifecycle rules, prototype defaults, and deferred enforcement. An organization can belong to some applications without belonging to others. A person receives that relationship only through an organization.

Goals and success measures

Non-goals

• Connect Midot sign-in, protect its pages or API, or partition its existing dataset by organization.
• Add individual app assignments, app-specific permissions, launch links, contracts, billing, or scheduled dates.
• Delete applications or memberships, or grant apps automatically when an administrator creates an organization.

Users and use cases

Use case: Manage access policy

• Actor: System administrator.
• Need: Maintain catalog records and organization memberships.
• Goal: Record the intended access policy for each organization.

Use case: View assigned apps

• Actor: Organization member of any supported role.
• Need: See assigned active applications and membership modes.
• Goal: Understand the organization's recorded access policy.

Requirements

PRD-0002-US-01: Manage applications

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a system administrator, I want an application catalog, so that I can manage available applications.
• Requirement: Create applications with an immutable UUID and slug, editable name and description, and a catalog status.
• Done when:
  • Name, description, and a unique lowercase slug are required. Names and descriptions can change. IDs and slugs cannot.
  • New applications start as Draft. The permitted lifecycle is Draft → Active ↔ Archived.
  • Only system administrators can create, edit, activate, archive, and reactivate applications.
  • Draft applications remain private to system administrators. No application deletion control exists.
  • Records include creation and update timestamps.

PRD-0002-US-02: Manage organization memberships

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a system administrator, I want organization app memberships, so that I can record which apps each organization can use.
• Requirement: Keep one persistent membership per organization and application, with an explicitly selected mode.
• Done when:
  • Only Active applications accept new memberships. Only system administrators can grant memberships or change saved modes.
  • The modes are Full access, Read-only, and Blocked. No membership means no access. All organization members inherit the relationship, subject to permissions.
  • Archiving overrides effective access to Blocked without changing saved modes or deleting data.
  • Administrators can edit saved modes while an app is Archived. Reactivation restores the saved modes, including Blocked.
  • Memberships retain their IDs and timestamps. Administrators block memberships instead of deleting them.
  • Organization deletion removes its memberships and retains the catalog and audit events.
  • Management requires authoritative access checks, fresh sessions for writes, and audited transactions. Impersonation cannot grant management access.

PRD-0002-US-03: View organization apps

• Story status: Current
• Replaces: N/A; extends PRD-0001-US-01.
• Replaced by: N/A
• User need: As an organization member, I want to see assigned applications, so that I can understand the organization's recorded access.
• Requirement: Show assigned Active apps on the organization Apps tab, including Blocked memberships.
• Done when:
  • Every organization role can see application names, descriptions, and modes. Unassigned, Draft, and Archived apps remain hidden.
  • The empty state explains that no active apps are assigned and directs the member to a system administrator.
  • The page includes no app launch links. It states that app access integration is pending and Midot does not enforce these modes yet.
  • Organization owners and administrators cannot edit application memberships. Nonmembers cannot view the list.
  • Forms provide labels, pending feedback, success notices, and error notices through existing components.

PRD-0002-US-04: Seed the prototype catalog

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a developer, I want prototype app records, so that I can exercise the catalog and membership flows.
• Requirement: Seed Midot as Active and Conveyal and TREDIS as Draft, with descriptions and stable slugs.
• Done when:
  • The prototype organization receives Full access to Midot.
  • Repeated seeds preserve administrator edits and existing membership modes.
  • Organizations created through administration receive no automatic memberships. There is no default-app setting or organization backfill.

Implementation

Services owns Application catalog and organization membership operations. The HTTP API and SDK expose them. Concourse shows catalog controls and the Apps tab. The prototype seed preserves administrator edits. Midot does not enforce these modes and the Apps tab has no launch links.

Experience and content

System administrators open Apps to manage the catalog. Each organization card links to Manage apps for membership grants and mode changes. Membership management shows the saved mode and the effective mode. Archive explanations describe the override and later restoration. The organization Apps tab shows app cards with no launch links. Existing loading boundaries and pending controls provide feedback.

Constraints and dependencies

Commands authorize authoritative administrator access once before validation and preparation. Accepted commands can finish after revocation. Current lifecycle, uniqueness, and membership facts are checked inside each transaction attempt. See Command outcomes.

Services own Application access policy and operations. The HTTP API exposes these operations, and Concourse calls them through the SDK. Auth owns identity, sessions, organization access, and system-administrator access. Persistence owns the schema and audited writes. Concourse owns forms, navigation, and notices.

Catalog activation alone does not integrate a separately deployed application. Future enforcement requires its own requirements and acceptance evidence.

User documentation

• Audience: System administrators, organization members, and developers.
• Tasks to explain: Maintain applications, grant memberships, change modes, and view assigned apps.
• Agreed terms: Application, Apps, Feature, Application membership, Full access, Read-only, Blocked, Draft, Active, Archived.
• Examples or screenshots needed: N/A; existing form patterns define the initial interface.
• Workspace README: Concourse application, with a link to this capability.

Revision history

• 2026-09-25 — PRD-0002-US-01 through PRD-0002-US-04: Replace the delivery notes with a summary of the current implementation, and accept the implemented stories. PR #168

References

• Organization overview
• Planning / Development Process