# Audit Logging Guidelines

## 1. Requirement
**Every state modification must be logged.**
Any action that creates, updates, or deletes data in the system must generate an entry in the `audit_logs` table. This applies to:
- User-initiated actions (API requests).
- AI-initiated actions.
- System-background actions (if impactful).

## 2. Implementation Mechanism
Use the `storage.createAuditLog` method available in `server/routes.ts` (via `storage` import) or `server/ai.ts`.

```typescript
await storage.createAuditLog({
  userId: number;          // The ID of the user performing the action (or context user).
  action: string;          // CREATE, UPDATE, DELETE, PURCHASE, SHARE, UNSHARE, etc.
  entityType: string;      // TASK, USER, LABEL, GOAL, REWARD, SYSTEM_SETTINGS, CONVERSATION.
  entityId: number | string | null; // ID of the modified entity.
  details: any;           // JSON object with relevant details (e.g., specific field updates).
  source: string;          // 'USER' (API/UI), 'AI' (Agent), 'SYSTEM'.
});
```

## 3. Best Practices
- **Do not** log sensitive data (passwords, tokens) in `details`.
- **Do** log high-level "diffs" or summary of changes (e.g., `{ status: 'done' }`).
- **Always** ensure `userId` is accurate. If it's a system action, use a designated system user ID or handle nullable logic if allowed (currently schema expects generic link but strongly typed).

## 4. Checklist for New Features
- [ ] Schema update (if new entity).
- [ ] API Route implementation.
- [ ] `createAuditLog` call added to SUCCESS path of route.
- [ ] `createAuditLog` call added to AI tool handler (if applicable).