Overview#
Argus enforces a formal, permission-gated lifecycle for every investigation, ensuring an immutable, court-ready audit trail from the first draft through closure, prosecution preparation, and archiving.
Operational intelligence investigations must move through well-defined stages, from initial drafting through active fieldwork, peer review, approval, and eventual closure. Without enforced state transitions and a permanent record of who changed what and why, audit reviewers cannot reconstruct the decision path that led to prosecution preparation, and accountability chains break down under legal scrutiny.
The platform implements a formal state machine for every investigation. Each transition is validated against a permission table, optionally requires a written justification, and is permanently written to an append-only audit log before the investigation record is updated, both writes occurring inside a single atomic transaction. The audit log is structurally append-only at the database privilege level, making the trail tamper-resistant even if higher-level application controls were bypassed.
Key Features#
-
Formal State Machine: Ten lifecycle states, DRAFT, OPEN, ACTIVE, PENDING_REVIEW, UNDER_REVIEW, APPROVED, PROSECUTION_PREP, CLOSED, ARCHIVED, and SUSPENDED, with a deterministic transition table. Any attempt to move to an undefined next state is rejected with a clear error before any data is written.
-
Permission-Gated Transitions: Every transition specifies the minimum permission tier required to execute it. Submitting requires submission rights; approving requires approval authority; closing requires close authority. Permissions are enforced at execution time, not merely at UI rendering time.
-
Justification-Required Transitions: Operationally significant transitions, suspending an active investigation, requesting peer review, closing, or rejecting back to active, require the acting user to supply a written justification. The justification is stored in the audit record and is visible in the transition history timeline.
-
Atomic Audit-Bound Writes: The audit record is inserted first, then the investigation state is updated, both inside a single atomic database transaction. If either write fails the entire transaction rolls back: it is impossible to change the investigation state without simultaneously creating the audit record.
-
Append-Only Audit Log: The audit log table has update and delete privileges explicitly revoked from the application database role. No row can be modified or removed after it is written, making the trail tamper-resistant at the infrastructure layer.
-
Machine Definition Export: The platform exposes the full state machine definition as a standards-conformant JSON document via the GraphQL API. This document can be consumed directly by state-chart visualisers, developer tooling, or compliance documentation generators.
-
Accessible State Badges: The current lifecycle state is rendered as a colour-coded badge that also carries a distinct icon and text label. Colour is never the sole indicator, satisfying WCAG 2.2 accessibility requirements.
-
Contextual Transition Controls: The platform queries the set of transitions available to the authenticated user's permission tier and renders them as action buttons. Transitions that require justification present a text input before proceeding, with full keyboard navigation and focus management meeting WCAG 2.2 AAA criteria.
-
Immutable Transition History Timeline: A chronological timeline displays every state change, the triggering event, the acting user, the timestamp, and any justification supplied. The timeline is read-only and shows the complete history without pagination.
-
Role-Based Access Control: Analyst, supervisor, and administrator permission tiers control access to investigations, with scoping at both the team and individual investigation level. Country-level and secrecy-level access controls are also enforced at the data layer.
Use Cases#
Legal and Compliance Audit#
Compliance officers and legal reviewers can reconstruct the complete decision history of an investigation: who submitted it, who assigned the investigator, who requested and began the peer review, who approved it, and who prepared the prosecution package. Every action is permanently on record with a timestamp and, where required, a written justification.
Operational Accountability#
Commanders and supervisors can see at a glance which investigations are awaiting review, which are suspended and why, and which have been approved for prosecution, all without needing to contact individual investigators.
Investigation Governance#
Quality assurance processes can enforce that no investigation reaches the CLOSED state without first passing through APPROVED, and that no investigation can be suspended without a documented written justification.
Prosecution Preparation#
Legal teams can track which investigations have entered the prosecution preparation stage and when, supported by a full audit trail of the approval chain that preceded it.
Multi-Stage Supervisor Review#
Supervisors can review, approve, or reject investigations back to active work, with documented feedback and revision tracking at each stage. Escalation paths are built directly into the state machine.
Integration#
Customers and developers interact with the investigation lifecycle through the platform's standard interfaces.
-
GraphQL API: Dedicated queries return the transition history for a specific investigation, the set of transitions available to the current user, and the full state machine definition as a JSON document. A single mutation executes a state transition, atomically writing both the new state and its audit record.
-
REST and Webhook Notifications: Investigation lifecycle events, state changes, escalations, approvals, can be subscribed to via the platform's webhook delivery system, enabling integration with external case management tools, notification services, and compliance reporting pipelines.
-
OAuth 2.0 / JWT Authentication: All API access is authenticated via the platform's standard OAuth 2.0 bearer token flow. Permission scopes are embedded in the JWT and are verified server-side on every transition request.
-
Normalised Event Model: Transition events emitted to webhooks follow a normalised model with consistent fields, investigation identifier, previous state, new state, acting user, timestamp, and justification, regardless of which transition occurred, making downstream processing straightforward.
-
RBAC Integration: The permission scopes that gate transitions the platform's defined investigation permission scopes (submit, assign, manage, review, approve, close, and archive) integrate directly with the platform's role-based access control system. Roles can be assigned at the tenant, team, or individual investigation level.
-
Dashboard and Workspace Surfaces: The investigation workspace surfaces the current state badge, available transition controls, and the full transition history timeline in a dedicated Lifecycle tab, requiring no custom integration for operators using the Argus portal.
Open Standards#
- W3C SCXML (State Chart XML): The W3C standard for hierarchical state machine notation; the underlying semantic model for the investigation lifecycle state chart.
- BPMN 2.0 (Object Management Group): Business Process Model and Notation; the workflow modelling standard whose concepts inform the investigation process stages and gateway logic.
- OAuth 2.0 (RFC 6749): The authorisation framework used for all API access; permission scopes are evaluated on every transition request.
- JSON Web Token (RFC 7519): The token format carrying authenticated user identity and permission scopes to the platform API.
- GraphQL (GraphQL Foundation): The API query language through which state machine definitions, transition history, and transition mutations are exposed.
- WCAG 2.2 (W3C Web Content Accessibility Guidelines): The accessibility standard met by the state badge and transition control components, ensuring colour is never the sole indicator of state and that keyboard navigation is fully supported.
Security and Compliance#
All investigation state transitions are permanently logged to an append-only audit trail. The audit record captures the acting user's identifier, their organisation, the action performed, the target investigation reference, and the wall-clock timestamp. Where a justification is required, its full text is stored alongside the event.
The audit log cannot be updated or deleted by the application layer. This architectural constraint means that no investigation can have its history silently altered after the fact, satisfying the data-integrity requirements of regulatory examination frameworks and supporting chain-of-custody obligations in prosecution contexts.
Tenant isolation is enforced at the data layer: every query and mutation is scoped to the authenticated user's organisation. No cross-tenant data access is possible regardless of the permission tier held within a single tenant.
Last Reviewed: 2026-04-14 / Last Updated: 2026-04-14