This epic serves to implement a unified state management and tracking system as described in [this architecture blueprint](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/group_and_project_operations_and_state_management/). # Problem statement Groups and Projects currently have inconsistent state management implementations that create several problems: **Current Issues:** - No consistency in group state management - No consistency in project state management - No consistency between group and project state management - State in descendants is sometimes inferred from ancestors inconsistently - No state history tracking. For instance, it's impossible to know when a project was archived, then unarchived, or when a group was transferred from another namespace - Different data models for similar operations (for example `group_deletion_schedules` vs `projects.marked_for_deletion_at` to track the "scheduled for deletion" state) - Performance issues with long-running synchronous operations (99.95th percentile: group transfer 51s, project transfer 27s) **Business Impact:** - Poor user experience due to inconsistent behavior and bugs - Poor user experience due to performance bottlenecks causing timeouts - Increased load on the Support and Engineering teams to resolve operations that failed due to timeouts or bugs - Difficulty in auditing and compliance - Maintenance overhead from duplicated and inconsistent code # Exit Criteria ## Goals - Establish a unified state management system for all namespace types - Provide consistent APIs and behavior across groups and projects - Enable state history tracking and audit capabilities - Improve performance by making appropriate operations asynchronous - Support metadata tracking (who initiated actions, error states, inheritance) - Reduce code duplication and maintenance overhead - Enable better observability and debugging capabilities ## Non-Goals - Complete rewrite of existing functionality (iterative migration approach) - Changes to user-facing APIs or UI in the initial implementation - Migration of non-state related group/project consolidation work - Performance optimizations unrelated to state management ### Participants - DRI: @aakriti.gupta - @shubhamkrai @smaglangit - PM: @jblack7 - EM: @mandrewsgl # Development Log <!-- STATUS NOTE START --> ## Status 2026-06-11 :clock1: **total hours spent this week by all contributors**: 15 hrs :tada: **achievements**: - Shane [added namespace_state_propagations outbox table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/237681) and model; the MR is merged. It introduces the transactional outbox table and model used for namespace state propagation to descendants. - Shubham [added notifications/activity](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/238936) for successful transfers, including user profile activity, group/project activity, and audit events. :issue-blocked: **blockers**: - None :arrow_forward: **next**: - Continue working on state propagation and groups & projects improvements _Copied from https://gitlab.com/groups/gitlab-org/-/epics/17954#note_3444040587_ <!-- STATUS NOTE END -->