​

SPEC 022 — Activity Tracking

---

​

1. Feature Purpose

Activity Tracking provides a comprehensive audit trail and action management system for organizations on the Equa platform. It captures three categories of activity: discrete user actions (e.g. cap table edits, document uploads), structured event logs for analytics and compliance, and organizational tasks (e.g. stock option exercises, compliance to-dos). Together these give admins visibility into what happened, when, and by whom — and let stakeholders act on pending items.

---

​

2. Current State (Verified)

​

2.1 Actions

​

2.2 Event Logs

​

2.3 Tasks

​

2.4 Exercise Option Tracking

​

2.5 Backend and Frontend

---

​

3. Data Model

​

Actions

​

EventLogs

​

Tasks

​

TasksExerciseOption

---

​

4. API Endpoints

---

​

5. Frontend Components

​

Frontend Behavior

• Activity feed — Displays a reverse-chronological list of actions with infinite scroll pagination.
• Filter bar — Users can filter by action type, user, and date range; filters update the URL query parameters.
• Task status transitions — Status changes trigger optimistic UI updates with rollback on API failure.
• Exercise option flow — The exercise form validates share counts against the grant’s vested/available balance before submission.
• Real-time updates — Activity feed does not auto-refresh; users pull to refresh or navigate away and back.

---

​

6. Business Rules

1. Immutable actions — Once recorded, actions cannot be edited or deleted; they serve as an audit trail.
2. Immutable event logs — EventLog entries are append-only; no updates or deletes are permitted.
3. Composite task uniqueness — The (entity, type, status) composite primary key ensures only one active task of a given type exists per entity. Status transitions create new rows rather than updating in place.
4. Task status machine — Tasks follow a defined state machine: pending → in_progress → completed or pending → cancelled. Backward transitions are not allowed.
5. Exercise validation — TasksExerciseOption.shares must not exceed the vested and unexercised balance of the referenced option grant.
6. Organization scoping — All activity queries are scoped to the requesting user’s organization; cross-org queries are not supported.
7. System events — EventLogs with user = null represent system-generated events (e.g. scheduled jobs, automated processes).
8. Event type conventions — Event types follow resource.action naming (e.g. cap_table.updated, document.uploaded, member.invited).
9. Action type registry — Action types are defined by UUID references; new types must be registered before use.
10. Feature requests — Feature request actions are a special action type that collects user feedback; they appear in the admin panel (SPEC 019) for review.

---

​

7. Acceptance Criteria

• Organization activity feed displays actions in reverse chronological order
• Actions can be filtered by type, user, and date range
• New actions are recorded with correct user, organization, and type references
• Actions are immutable — no edit or delete endpoints exist
• Event logs capture structured event data with correct type and payload
• Event logs are append-only with no update or delete capability
• Tasks display with correct status badges (pending, in_progress, completed, cancelled)
• Task status transitions follow the defined state machine
• Backward status transitions are rejected by the API
• Exercise option tasks validate share count against available vested balance
• Exercise option form prevents submission when shares exceed available balance
• Feature requests are recorded as actions and visible in admin panel
• All activity queries are scoped to the requesting user’s organization
• Pagination works correctly for large activity feeds (100+ items)

---

​

8. Risks