Version: Next

Audit & compliance

The audit system provides a complete record of all activities in the platform. It captures who did what, when, and where to support security monitoring, compliance requirements, and incident investigation.

Foundation → Audit & Compliance (segment: foundation/audit)

Sub-section	Path	Description
Audit Logs	`foundation/audit/logs`	Activity records
Alerts	`foundation/audit/alerts`	Security notifications
Exports	`foundation/audit/exports`	Compliance reports
Retention	`foundation/audit/retention`	Data lifecycle

Audit architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                          Audit System                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                     Activity Capture                             │    │
│  │                                                                   │    │
│  │  User Actions → API Events → System Events → Security Events     │    │
│  │                                                                   │    │
│  └────────────────────────────────┬────────────────────────────────┘    │
│                                   │                                      │
│                                   ▼                                      │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────┐   │
│  │  Audit Logs  │    │    Alerts    │    │       Analytics          │   │
│  │              │    │              │    │                          │   │
│  │ • Entries    │    │ • Threshold  │    │ • Trends                 │   │
│  │ • Categories │    │ • Pattern    │    │ • Statistics             │   │
│  │ • Severities │    │ • Anomaly    │    │ • Reports                │   │
│  │ • Actors     │    │ • Security   │    │ • Dashboards             │   │
│  └──────────────┘    └──────────────┘    └──────────────────────────┘   │
│          │                   │                        │                  │
│          ▼                   ▼                        ▼                  │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                    Compliance & Exports                           │   │
│  │                                                                   │   │
│  │  JSON • CSV • XLSX • PDF  │  Retention Policies  │  Archive      │   │
│  │                                                                   │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Part 1: Audit logs

Audit logs record every significant action in the system.

Audit entry properties

Field	Type	Description
`id`	string	Unique log ID
`tenantId`	string	Tenant scope
`timestamp`	datetime	When it occurred
`category`	enum	Event category
`severity`	enum	Importance level
`status`	enum	Completion status
`action`	string	Action performed
`resource`	string	Target resource
`resourceId`	string	Target ID
`actorId`	string	Who performed
`actorType`	enum	Actor classification
`actorEmail`	string	Actor email
`ipAddress`	string	Client IP
`userAgent`	string	Client info
`location`	object	Geo-location
`metadata`	object	Additional data
`previousValue`	object	Before change
`newValue`	object	After change

Audit categories

Category	Description	Examples
`authentication`	Login/logout events	Login, logout, MFA verify
`authorization`	Access control events	Permission check, role assign
`data_access`	Data read operations	View student, export report
`data_modification`	Data write operations	Create, update, delete
`system`	System events	Config change, service start
`security`	Security events	Password change, device trust
`compliance`	Compliance events	Audit export, policy change
`admin`	Admin operations	User create, role modify

Severity levels

Severity	Description	Use case
`info`	Informational	Normal operations
`warning`	Notable event	Unusual but not critical
`error`	Error occurred	Failed operations
`critical`	Critical event	Security incidents

Audit statuses

Status	Description
`success`	Action completed
`failure`	Action failed
`pending`	Action in progress
`cancelled`	Action cancelled

Actor types

Type	Description
`user`	Human user
`service`	Service account
`system`	System process
`api`	API client
`scheduler`	Scheduled task

What gets logged

Category	Events
Authentication	Login, logout, MFA setup, MFA verify, password change, password reset, session terminate
Users	Create, update, delete, activate, deactivate, lock, unlock, role assign, role remove
Roles	Create, update, delete, permission add, permission remove
Students	Create, update, delete, enroll, transfer, graduate, import
Finance	Invoice create, payment record, receipt issue, fee adjust
Grades	Grade enter, grade update, report generate
Settings	Config change, policy update, feature toggle
Security	Device trust, alert acknowledge, export request

Viewing audit logs

Navigate to Foundation → Audit & Compliance → Audit Logs
View log entries with:
- Timestamp
- Actor (who)
- Action (what)
- Resource (target)
- Status (result)
- Severity badge
Filter by category, severity, date, actor
Click entry for full details

Audit log filters

Filter	Options
Date range	From/to dates
Category	Auth, data, security, etc.
Severity	Info, warning, error, critical
Status	Success, failure, pending
Actor	Specific user
Resource	Specific resource type
IP address	Client IP

Searching audit logs

Search capabilities:
- By actor email
- By resource ID
- By action name
- By IP address
- Full-text in metadata

Audit log entry detail

When viewing an entry:

Section	Content
Summary	Timestamp, actor, action, resource
Context	IP, user agent, location
Changes	Previous value → New value
Metadata	Additional context data
Related	Related log entries

Part 2: Alerts

Alerts notify administrators of important events that require attention.

Alert properties

Field	Type	Description
`id`	string	Alert ID
`tenantId`	string	Tenant scope
`type`	enum	Alert type
`severity`	enum	Importance
`title`	string	Alert title
`message`	string	Description
`source`	string	Origin system
`triggeredAt`	datetime	When triggered
`acknowledgedAt`	datetime	When acknowledged
`acknowledgedBy`	string	Who acknowledged
`resolvedAt`	datetime	When resolved
`resolvedBy`	string	Who resolved
`metadata`	object	Additional data

Alert types

Type	Description	Example
`threshold`	Metric exceeded limit	Too many failed logins
`pattern`	Suspicious pattern detected	Unusual access pattern
`anomaly`	Anomalous behavior	Login from new country
`security`	Security event	Compromised device detected

Alert severity

Severity	Response
`info`	Awareness only
`warning`	Review when convenient
`error`	Investigate soon
`critical`	Immediate action required

Alert lifecycle

Alert Triggered
      │
      ▼
┌──────────────┐
│    Active    │
└──────┬───────┘
       │
       ▼
 Acknowledge?
   │       │
  Yes      No (escalate)
   │       │
   ▼       ▼
┌──────────────┐
│ Acknowledged │
└──────┬───────┘
       │
       ▼
  Investigate
       │
       ▼
   Resolved?
   │       │
  Yes      No
   │       │
   ▼       ▼
┌──────────────┐
│   Resolved   │ → Escalate/Reopen
└──────────────┘

Viewing alerts

Navigate to Foundation → Audit & Compliance → Alerts
View alert list with:
- Severity indicator
- Type badge
- Title and message
- Triggered time
- Status
Filter by type, severity, status
Click alert for details

Acknowledging an alert

Open alert details
Review alert information
Click Acknowledge
Add optional notes
Alert moves to acknowledged status

Resolving an alert

Open acknowledged alert
Verify issue is addressed
Click Resolve
Add resolution notes
Alert moves to resolved status

Alert notifications

Alerts can trigger:

In-app notification
Email to admins
Webhook to external system

Part 3: Exports

Export audit data for compliance reporting and external analysis.

Export properties

Field	Type	Description
`id`	string	Export ID
`tenantId`	string	Tenant scope
`type`	string	Export type
`format`	enum	File format
`status`	enum	Export status
`filters`	object	Applied filters
`requestedBy`	string	Who requested
`requestedAt`	datetime	When requested
`completedAt`	datetime	When finished
`expiresAt`	datetime	Download expiry
`fileUrl`	string	Download URL
`fileSize`	number	Size in bytes
`recordCount`	number	Records exported

Export formats

Format	Description	Use case
`json`	JSON format	API integration
`csv`	Comma-separated	Spreadsheet analysis
`xlsx`	Excel format	Business reporting
`pdf`	PDF document	Official records

Export statuses

Status	Description
`pending`	Queued for processing
`processing`	Being generated
`completed`	Ready for download
`failed`	Generation failed
`expired`	Download expired

Creating an export

Navigate to Foundation → Audit & Compliance → Exports
Click New Export
Configure export:
- Select date range
- Choose categories to include
- Select format (JSON, CSV, XLSX, PDF)
- Add filters if needed
Click Generate
Export processes in background
Download when complete

Export templates

Save common export configurations:

Template	Content
Monthly compliance	All activity for month
Security report	Auth and security events
User activity	Specific user history
Data access	All data read operations

Scheduled exports

Configure automatic exports:

Daily security summary
Weekly compliance report
Monthly full audit

Part 4: Retention policies

Retention policies control how long audit data is kept.

Retention policy properties

Field	Type	Description
`id`	string	Policy ID
`tenantId`	string	Tenant scope
`name`	string	Policy name
`description`	string	Policy purpose
`category`	enum	Target category
`retentionDays`	number	Days to retain
`archiveDays`	number	Days before archive
`deleteDays`	number	Days before delete
`isActive`	boolean	Policy active

Default retention periods

Category	Active	Archive	Delete
Authentication	90 days	365 days	730 days
Data access	90 days	365 days	730 days
Data modification	365 days	730 days	2555 days
Security	365 days	730 days	2555 days
Compliance	365 days	2555 days	Never

Retention lifecycle

New Log Entry
      │
      ▼
┌──────────────┐
│    Active    │  ← Quick access
│  (Hot store) │
└──────┬───────┘
       │ After retentionDays
       ▼
┌──────────────┐
│   Archived   │  ← Compressed storage
│ (Cold store) │
└──────┬───────┘
       │ After archiveDays
       ▼
┌──────────────┐
│   Deleted    │  ← Permanent removal
└──────────────┘

Configuring retention

Navigate to Foundation → Audit & Compliance → Retention
View current policies by category
Click policy to edit
Adjust retention periods
Save changes

Legal hold

For compliance or legal requirements:

Place hold on specific data
Data won't be archived or deleted
Remove hold when no longer needed

Compliance reporting

Common compliance requirements

Standard	Audit needs
GDPR	Data access logs, consent records
FERPA	Education records access
SOC 2	Security controls evidence
Internal	Policy compliance checks

Compliance dashboard

Metric	Description
Total events	Events in period
By category	Breakdown by type
By severity	Error/critical count
Access patterns	Data access summary
Security events	Security incidents

Generating compliance reports

Navigate to Audit & Compliance → Reports
Select report template
Choose date range
Generate report
Download or schedule

Security monitoring

Real-time monitoring

Metric	Alert threshold
Failed logins	> 10 in 5 min
Password resets	> 5 per hour
Data exports	> 3 per day
Permission changes	Any (audit)
Admin actions	Any (audit)

Security dashboard metrics

Widget	Shows
Auth summary	Login success/fail rate
Active sessions	Current user count
Alert status	Active alerts
Recent activity	Live activity feed

Permissions required

Action	Required permission
View audit logs	`audit.view`
Search audit logs	`audit.search`
Export audit logs	`audit.export`
View alerts	`alerts.view`
Manage alerts	`alerts.manage`
View retention	`retention.view`
Manage retention	`retention.manage`

Best practices

Audit logging

Review logs weekly
Monitor failed authentications
Track permission changes
Investigate anomalies promptly

Alert management

Respond to critical alerts immediately
Acknowledge alerts within 24 hours
Document resolution steps
Review alert patterns monthly

Compliance

Schedule regular exports
Maintain retention policies
Document compliance evidence
Review access patterns

Data retention

Align with legal requirements
Archive rather than delete
Use legal hold when needed
Review policies annually

Troubleshooting

Cannot find log entry

Causes:

Entry outside date range
Entry archived
Insufficient filter criteria

Fix:

Expand date range
Check archived logs
Broaden search filters

Export stuck in processing

Causes:

Large data volume
System load high
Process interrupted

Fix:

Wait for completion (large exports take time)
Cancel and retry with narrower filters
Contact support if persists

Alerts not triggering

Causes:

Threshold not met
Alert rule disabled
Notification settings incorrect

Fix:

Review alert rules
Check rule is active
Verify notification settings

Retention policy not applied

Causes:

Policy not active
Processing schedule not run
Legal hold in place

Fix:

Verify policy is active
Check processing schedule
Review any legal holds

Identity & access management — Users, roles, permissions
Sessions, MFA & device trust — Authentication security
Security overview — Security architecture

Navigation path​

Audit architecture​

Part 1: Audit logs​

Audit entry properties​

Audit categories​

Severity levels​

Audit statuses​

Actor types​

What gets logged​

Viewing audit logs​

Audit log filters​

Searching audit logs​

Audit log entry detail​

Part 2: Alerts​

Alert properties​

Alert types​

Alert severity​

Alert lifecycle​

Viewing alerts​

Acknowledging an alert​

Resolving an alert​

Alert notifications​

Part 3: Exports​

Export properties​

Export formats​

Export statuses​

Creating an export​

Export templates​

Scheduled exports​

Part 4: Retention policies​

Retention policy properties​

Default retention periods​

Retention lifecycle​

Configuring retention​

Legal hold​

Compliance reporting​

Common compliance requirements​

Compliance dashboard​

Generating compliance reports​

Security monitoring​

Real-time monitoring​

Security dashboard metrics​

Permissions required​

Best practices​

Audit logging​

Alert management​

Compliance​

Data retention​

Troubleshooting​

Cannot find log entry​

Export stuck in processing​

Alerts not triggering​

Retention policy not applied​

Related documentation​

Navigation path

Audit architecture

Part 1: Audit logs

Audit entry properties

Audit categories

Severity levels

Audit statuses

Actor types

What gets logged

Viewing audit logs

Audit log filters

Searching audit logs

Audit log entry detail

Part 2: Alerts

Alert properties

Alert types

Alert severity

Alert lifecycle

Viewing alerts

Acknowledging an alert

Resolving an alert

Alert notifications

Part 3: Exports

Export properties

Export formats

Export statuses

Creating an export

Export templates

Scheduled exports

Part 4: Retention policies

Retention policy properties

Default retention periods

Retention lifecycle

Configuring retention

Legal hold

Compliance reporting

Common compliance requirements

Compliance dashboard

Generating compliance reports

Security monitoring

Real-time monitoring

Security dashboard metrics

Permissions required

Best practices

Audit logging

Alert management

Compliance

Data retention

Troubleshooting

Cannot find log entry

Export stuck in processing

Alerts not triggering

Retention policy not applied

Related documentation