Admin Audit Trail

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• docs/PLAN.md
• CLAUDE.md
• src/middleware.ts
• src/lib/audit.ts

The Admin Audit Trail records all administrative actions performed within the Inkweave Admin interface. This system provides a permanent, searchable record of modifications to users, content, and system configurations to ensure accountability and security. It operates as a restricted internal module available only to authenticated administrators.

Sources: README.md:3-5, docs/PLAN.md

System Architecture

The audit system integrates with the Next.js application layer to intercept and log state-changing operations. It leverages Vercel Authentication to identify the specific administrator performing an action.

Data Flow

Administrative requests pass through a validation layer before the system executes the command and commits the audit entry. The following diagram illustrates the lifecycle of a logged admin action:

The system ensures that audit logging occurs alongside the primary data operation. If the audit log fails, the primary operation should roll back to maintain data integrity.

Sources: README.md:7-9, src/middleware.ts, src/lib/audit.ts

Authentication and Security

Access to the audit trail requires a valid Vercel login. The application uses a private deployment strategy to isolate administrative tools from the public Inkweave application.

• Vercel Login: Protects the entire admin project deployment.
• Middleware Enforcement: Validates session tokens on every request to inkweave-admin.
• Submodule Isolation: Maintains admin logic in a separate repository to prevent leaking internal tools into the public upstream/inkweave repository.

Sources: README.md:7-9, src/middleware.ts

Audit Data Model

The system stores audit logs in a dedicated database table. Each entry captures the identity of the actor, the nature of the change, and the targeted resource.

Field	Type	Description
id	UUID	Unique identifier for the audit entry.
admin_id	String	The identifier of the admin retrieved from Vercel session.
action_type	Enum	Categorization of the action (e.g., DELETE_USER, UPDATE_POST).
resource_id	String	The ID of the entity being modified.
payload	JSONB	The state of the data before and after the change.
timestamp	TIMESTAMPTZ	The exact time the action was performed.

Sources: src/lib/audit.ts, docs/PLAN.md

Implementation Guidelines

Developers must follow specific logging rules defined in the project guidelines. These rules ensure consistency across the administrative toolset.

1. Mandatory Logging: Log all destructive actions (deletions) and sensitive configuration changes.
2. Context Inclusion: Include the original state of the object in the payload field to allow for potential recovery or verification.
3. Active Voice: Write action descriptions using clear, present-tense verbs.

The sequence ensures the audit entry exists before the user receives confirmation of the change.

Sources: CLAUDE.md, src/lib/audit.ts

Conclusion

The Admin Audit Trail serves as a critical security component for the Inkweave ecosystem. By centralizing logs within a Vercel-protected admin environment, the system maintains a high degree of operational transparency while shielding sensitive management tools from public access. The integration of submodule architecture ensures that these internal tracking mechanisms remain distinct from the consumer-facing platform.

Sources: README.md:3-9, docs/PLAN.md