Build Asset History and Audit Trail System

[yusuftomilola]

Description

Implement a comprehensive audit trail system that tracks all changes to assets and related entities, providing complete history and accountability for compliance and reporting.

Requirements

AssetHistory Entity:

AssetHistory {
  id: UUID (primary key)
  asset: ManyToOne -> Asset
  eventType: enum (CREATED, UPDATED, ASSIGNED, TRANSFERRED, STATUS_CHANGED, 
                   MAINTENANCE_SCHEDULED, MAINTENANCE_COMPLETED, RETIRED, 
                   DOCUMENT_ADDED, DOCUMENT_REMOVED, NOTE_ADDED, DELETED)
  actor: ManyToOne -> User (who performed the action)
  changes: jsonb (before/after values)
  metadata: jsonb (additional context)
  ipAddress: string (optional)
  userAgent: string (optional)
  timestamp: timestamp
  relatedEntity: string (optional - e.g., transfer ID, maintenance ID)
  relatedEntityType: string (optional)
}

AuditLog Entity:

AuditLog {
  id: UUID (primary key)
  entityType: string (Asset, Department, User, etc.)
  entityId: UUID
  action: enum (CREATE, READ, UPDATE, DELETE)
  actor: ManyToOne -> User
  changes: jsonb (detailed change log)
  metadata: jsonb
  ipAddress: string
  userAgent: string
  endpoint: string (API endpoint called)
  method: string (GET, POST, PUT, DELETE)
  statusCode: integer (HTTP response code)
  requestId: string (correlation ID)
  duration: integer (milliseconds)
  timestamp: timestamp
}

API Endpoints:

• GET /api/v1/assets/:id/history - Get asset history timeline
• GET /api/v1/assets/:id/history/:eventType - Filter history by event type
• GET /api/v1/audit-logs - Get system-wide audit logs (admin only)
• GET /api/v1/audit-logs/entity/:type/:id - Get audit logs for specific entity
• GET /api/v1/audit-logs/user/:userId - Get all actions by specific user
• GET /api/v1/audit-logs/export - Export audit logs to CSV/JSON
• GET /api/v1/audit-logs/statistics - Get audit statistics (events per day, top actors)
• POST /api/v1/audit-logs/search - Advanced search with multiple filters

Business Logic:

• Auto-create history entry on every asset modification
• Calculate and store field-level changes (diff)
• Capture user context from JWT token
• Store IP address and user agent from request headers
• Link related events (e.g., transfer and assignment change)
• Support filtering by date range, event type, actor
• Implement efficient pagination for large history sets
• Retain audit logs indefinitely (configurable retention policy)
• Anonymize data on user deletion (GDPR compliance)

Change Tracking Format:

{
  field: "status",
  oldValue: "ACTIVE",
  newValue: "MAINTENANCE",
  changedAt: "2025-01-19T10:30:00Z",
  changedBy: "user-id"
}

Validation Rules:

• Event type must be valid enum value
• Actor must be authenticated user
• Changes object must be valid JSON
• Timestamp must be accurate server time
• IP address must be valid format

Technical Specifications

• Use TypeORM subscribers/listeners to auto-create history entries
• Implement middleware to capture request context
• Store audit logs in separate database/schema for isolation
• Use partitioning for audit_logs table (partition by month)
• Create indexes on: asset_id, actor_id, timestamp, event_type
• Implement full-text search on changes/metadata fields (PostgreSQL tsvector)
• Use database triggers as fallback for critical operations
• Implement log streaming to external services (optional - ELK stack)
• Add request correlation IDs for tracing

Acceptance Criteria

• Every asset change creates history entry automatically
• Change diffs are accurate and complete
• User context is captured correctly
• History timeline displays events chronologically
• Filtering and search work efficiently
• Pagination handles large result sets (10,000+ entries)
• Audit logs are immutable (cannot be edited or deleted)
• Export functionality generates valid CSV/JSON
• Statistics API returns accurate aggregations
• System performance is not degraded by logging

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[nottherealalanturing]

@nottherealalanturing has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to take this on. I’ll implement a comprehensive audit trail covering asset history and system-wide audit logs, with automatic change tracking, accurate diffs, and full user/request context. Ready to start once assigned.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @nottherealalanturing to this issue.

[okekefrancis112]

@okekefrancis112 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to work on this issue because it addresses a core backend concern around reliability, correctness, and scalability. I enjoy contributing to backend features that improve system behavior, data integrity, and developer experience.

I have strong experience building and maintaining backend systems using NestJS, Node.js, TypeScript, SQL/NoSQL databases, and RESTful APIs. I’ve worked on production features involving data modeling, validation, background processing, performance optimization, and debugging complex edge cases. I’m comfortable reading existing codebases, following established patterns, writing tests where appropriate, and shipping well-documented changes that integrate cleanly with frontend and infrastructure requirements.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @okekefrancis112 to this issue.

[drips-wave]

Congratulations, @nottherealalanturing! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on January 31, 2026.

🧑‍💻 @nottherealalanturing: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

⚠️ Important: When opening a PR, please link it to this issue to ensure it gets tracked accurately.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[respp]

@respp has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello DistinctCodes team! Can I take this issue?

I'm a developer with a solid background in Web3, working across both front-end and back-end. Currently, I'm a maintainer at Koopay and StellarRent, where I lead the development of smart contracts and decentralized infrastructure. You can check out my profile to see my contributions to the most important projects within the Stellar ecosystem.

Additionally, I have experience working in other ecosystems such as StarkNet, Optimism, and Worldcoin, with a focus on building scalable, secure, and efficient blockchain applications.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @respp to this issue.

[ryzen-xp]

@ryzen-xp has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi maintainers 👋
I’m a blockchain developer with strong expertise in Stellar, Rust,TS and Stellar SDK integrations. I’ve worked on multiple Stellar-based smart contract and backend systems.

I understand the scope of this issue and can deliver a reliable, production-quality solution with proper tests and documentation.
Plz assign me !!

ETA: 12 hours

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ryzen-xp to this issue.

[FabianSanchezD]

@FabianSanchezD has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hey team! I'm Fabian and I'd like to work on this issue. I have experience with databases and I'd like to approach the problem!

I'll deliver quality work, thanks!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @FabianSanchezD to this issue.

[martinvibes]

@martinvibes has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to work on this issue because it aligns with my experience building and contributing to web and blockchain projects. I’m comfortable working across frontend and smart contract codebases and delivering clean, well-structured solutions.

I’ve reviewed the issue and repository and can implement a reliable fix while following the project’s standards. I communicate progress clearly and iterate quickly based on feedback. I’d be happy to take this on and would appreciate being assigned.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @martinvibes to this issue.

[ShantelPeters]

@ShantelPeters has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I would like to work on this issue , kindly assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ShantelPeters to this issue.