0003: Projects
Organization-owned Projects with shared identities and explicit access
- ID: PRD-0003
- Status: Accepted
- Decision maker: Trevor Gerhardt
- Scope: Concourse organization and system administration, 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: Not applicable. The owner requested implementation of the agreed plan directly.
- Related designs: Not applicable. The interface uses existing forms, navigation, and notices.
- Related ADRs: Services ownership
- Related user documentation: Not yet published. The Concourse application README lists the Project routes but does not explain the Project tasks.
Summary
A Project groups an organization's work and data across Applications. Each Project has one stable identity and explicit access rules. Concourse provides Project administration. Individual Applications do not use Project selection or data in this checkout.
User problem and evidence
The owner needs a common unit below Organization for work across Applications. Organization membership alone must not expose every Project. The planning interview settled roles, archive behavior, support access, shared identity, and the first delivery boundary. The owner then requested implementation of these requirements in this task.
Goals and success measures
| Goal | Measure | Target |
|---|---|---|
| Share identity across Applications | Schema and guarded query checks | One immutable Project UUID and organization |
| Restrict Project access | Services, API, and browser checks | Every role follows the access matrix |
| Preserve work through archiving | Lifecycle checks | Data, IDs, and grants survive archive and restore |
| Make management available | Browser acceptance flows | Organization and system administrators can complete each management task |
Non-goals
- Integrate Midot, add app launch links, or enforce Project access inside an external Application.
- Add geographic regions, counties, other app data, a metadata editor, or configurable fields.
- Add Project slugs, organization transfers, individual Project deletion, or a session-wide active Project.
- Assign Applications per Project or combine Project grants with email invitations.
Users and use cases
Use case: Administer organization work
- Actor: Organization owner/admin, or system administrator acting as themselves.
- Need: Create Projects, describe work, assign access, and archive completed work.
- Goal: Keep control of Project identity and access without losing data.
Use case: Open assigned work
- Actor: Organization member or viewer with explicit Project membership.
- Need: Find accessible Projects and read their details.
- Goal: Use one Project identity across the current Project operations.
Requirements
PRD-0003-US-01: Create and describe Projects
- Story status: Current
- Replaces: N/A
- Replaced by: N/A
- User need: As an administrator, I want to create and describe Projects, so that my organization can organize its work.
- Requirement: Create Active Projects with an immutable UUID and organization, editable title and description, and timestamps.
- Done when:
- Organization owners/admins can create Projects. System administrators can do so without organization membership.
- Title and description are required plain text. Trim whitespace and limit them to 191 and 4,000 characters, respectively.
- Titles can repeat. Updates preserve the ID, organization, and creation time.
- Creation saves no creator membership. Existing and new organizations receive no default Project.
- Members and viewers cannot create Projects or edit their title and description.
PRD-0003-US-02: Manage explicit Project memberships
- Story status: Current
- Replaces: N/A
- Replaced by: N/A
- User need: As an administrator, I want to assign Project roles, so that each person receives access to the work they need.
- Requirement: Save one Member or Viewer grant per Project and current organization membership.
- Done when:
- Only organization owners/admins and system administrators can grant, change, or revoke access.
- Grants target existing members/viewers of the same organization. Organization invitations remain separate.
- Owners/admins inherit administrative access. Their access cannot be revoked at the Project level.
- Organization viewers remain read-only even with a saved Member grant.
- Role changes preserve saved grants. Promotions override them with inherited access. Demotions apply any saved grant.
- Creation or previous administrative access alone grants nothing after demotion.
- Removing organization membership deletes its Project grants. Rejoining requires new grants.
- The editor distinguishes saved roles, effective access, and inherited access.
PRD-0003-US-03: Find and open accessible Projects
- Story status: Current
- Replaces: N/A
- Replaced by: N/A
- User need: As an organization member, I want to find my Projects, so that I can open the work available to me.
- Requirement: Show accessible active Projects on the organization landing page and provide a detail page for each.
- Done when:
- The landing page lists Project titles, descriptions, IDs, and effective access.
- Each detail page shows the Project title, description, ID, status, and effective access.
- Unassigned Projects expose no details through lists or direct links. Unknown and inaccessible Project links show the same denial.
- Owners/admins can open every active Project in their organization.
- System administrators have a separate Manage projects entry. Ordinary organization routes still require actual organization membership.
- System-administrator support access cannot derive from impersonation. An impersonated person retains only that person's normal access.
- The Apps tab preserves the Application list and integration notice from PRD-0002. Organization selection and SSO still open the landing page.
- Empty states explain how to create a Project or obtain access. Forms and navigation provide pending, success, and error feedback.
PRD-0003-US-04: Archive and restore Projects
- Story status: Current
- Replaces: N/A
- Replaced by: N/A
- User need: As an administrator, I want to archive completed Projects, so that active work remains easy to find without deleting past work.
- Requirement: Support Active ↔ Archived transitions while preserving identity, data, and saved grants.
- Done when:
- Only organization owners/admins and system administrators can archive, view archived Projects, manage their access, and restore them.
- Members/viewers cannot open an archived Project, including through a previously valid link.
- Administrators must restore a Project before editing its details.
- An administrator-only archive view lists archived Projects. Restoration applies the preserved grants under current organization roles.
- No individual Project deletion control exists.
- Organization deletion removes active and archived Projects and grants. Audit history remains.
PRD-0003-US-05: Share identity and compose Application access
- Story status: Retired
- Replaces: N/A
- Replaced by: PRD-0003-US-06
- History: The original story combined the shared Project foundation with Application data enforcement. Application integration is outside the current capability.
PRD-0003-US-06: Share Project identity
- Story status: Current
- Replaces: PRD-0003-US-05
- Replaced by: N/A
- User need: As an Application developer, I want one Project identity, so that related work has one stable reference.
- Requirement: Store one Project UUID per organization Project and expose it through guarded Services, API, and SDK operations.
- Done when:
- A Project keeps its UUID when its title, access, or archive state changes.
- Project operations use one shared identity and do not create Application-specific Project records.
- The foundation has no unused metadata store or Application integration endpoint.
Implementation
Services owns Project commands and queries through the HTTP API and SDK. Concourse shows accessible Projects, administration controls, and archived Projects. Persistence stores one Project identity and explicit grants. The current checkout does not connect Application data to Projects.
Experience and content
The organization navigation starts with Projects, then Apps. Members and SSO keep their existing role restrictions. Administrators create a Project from the landing page, open its detail page, and manage details, access, or lifecycle there. System administrators reach the same controls through Manage projects on an organization card. Archived Projects require an explicit archive view. The access editor explains preserved grants and organization viewer limits. All controls use labels, keyboard-accessible native fields, pending feedback, and existing Notice behavior.
Constraints and dependencies
Services authorize each command once before validation and preparation. Accepted commands can finish after access is revoked, including on retries. Current Project state and membership relationships remain transactional. Command outcomes defines this timing and the audit outcomes. The HTTP API exposes these operations. Concourse uses the SDK and maps API outcomes to pages, notices, and denial screens. Auth owns identity, sessions, organization access, and system-administrator access. Persistence owns schema, foreign keys, migrations, and audit transactions. Protected reads do not retain access results across requests.
The Project membership and access stories above record the access matrix and support exception.
User documentation
- Audience: Organization members, organization administrators, system administrators, and Application developers.
- Tasks to explain: Find Projects, manage details and access, archive, and restore.
- Agreed terms: Project, Project membership, Project access, Member, Viewer, Active, Archived, shared Project data, Application-specific Project data.
- Examples or screenshots needed: Project access editor, archive view, and member/viewer detail pages.
- Published documentation: Not yet published. The Concourse application README lists the Project routes but does not explain the Project tasks.
Revision history
- 2026-09-25 — PRD-0003-US-01 through PRD-0003-US-06: Accept the implemented stories. Remove future app data from the PRD-0003-US-04 restore rule. Retire PRD-0003-US-05, because it combined the shared Project identity with Application data enforcement. Add PRD-0003-US-06 for the shared identity. Replace the delivery notes with a summary of the current implementation. PR #168