CAS/DISOT - Decentralized Content Management System

A decentralized content management system implementing Content Addressable Storage (CAS) and Decentralized Immutable Source of Truth (DISOT) with digital signatures.

🚀 Features

Content Addressable Storage (CAS)

• SHA-256 Hashing: Every piece of content is addressed by its cryptographic hash
• Automatic Deduplication: Identical content is stored only once
• Content Integrity: Hash verification ensures content hasn't been tampered with
• Metadata Support: Store additional information alongside content
• Multiple Storage Providers: In-memory, IndexedDB, IPFS, and Helia (browser-native IPFS)

DISOT (Decentralized Immutable Source of Truth)

• Digital Signatures: Create cryptographically signed entries
• Entry Types: Support for BLOG_POST, DOCUMENT, IMAGE, and SIGNATURE types
• Signature Verification: Verify the authenticity of any entry
• Timestamp Proof: Each entry includes a timestamp for temporal ordering
• Blog Post Support: Create blog posts directly within DISOT entries

User Interface

• Modern Angular 18: Built with standalone components
• Responsive Design: Works seamlessly on desktop and mobile
• File Upload: Drag-and-drop or click to upload
• Content Browser: Search and preview stored content with multiple view formats
• Entry Management: Create and verify DISOT entries
• Content Preview: View content as Text, JSON, Hex, Base64, or Image
• Modal Selection: Elegant content selection with preview capability
• Previous Entries: View and preview historical DISOT entries

New in v3.3.0

• Automatic MIME Type Detection: Content references now auto-detect MIME types
• Enhanced Metadata Entry: Author and previous version hash selection via modal
• Improved UX: Streamlined content selection across the application

New in v3.2.0

• Author Selection Modal: Browse and select author hashes
• Previous Version Selection: Visual selection for version tracking
• Metadata Improvements: Enhanced metadata entry workflow

New in v3.1.0

• Hash Selection for Records: Browse and select hashes from CAS
• Reusable Content Selection: Unified modal component
• Code Refactoring: Removed duplicate services, improved code reuse

New in v3.0.1

• Fixed CI Test Failures: Resolved race conditions and test mocking issues
• Budget Adjustment: Increased bundle size limits for Helia dependencies
• Test Coverage: All 402 tests now passing with 78.08% code coverage

New in v3.0.0 - IPFS Integration

• IPFS Storage Provider: Distributed storage using external IPFS node
• Helia Storage Provider: Browser-native IPFS implementation with IndexedDB
• Content Migration: Migrate existing content from local storage to IPFS/Helia
• Share Links: Generate shareable IPFS gateway URLs for content
• Upload Queue: Persistent queue with retry logic for IPFS uploads
• Health Monitoring: Real-time IPFS node health status indicators
• Hybrid Storage: Local caching with distributed IPFS backend
• Migration UI: Bulk content transfer with progress tracking

📋 Table of Contents

• Live Demo
• Installation
• Quick Start
• Architecture
• Development
• Deployment
• Testing
• Documentation
• GitFlow Workflow
• Contributing

🌐 Live Demo

Production Environment

🚀 https://o2alexanderfedin.github.io/angular-cas-disot

Staging Environment

🎭 https://o2alexanderfedin.github.io/angular-cas-disot/staging

Coverage Reports

📊 https://o2alexanderfedin.github.io/angular-cas-disot/coverage/cas-app/

Note: Both environments are currently updated from the master branch. The staging environment provides a testing ground for validating changes before they go live.

• Roadmap

🛠 Installation

Prerequisites

• Node.js v20.19+ or v22.12+ (required for Angular CLI v20)
• npm v9+
• Git

⚠️ Important: Angular CLI v20 requires Node.js v20.19+ or v22.12+. Earlier versions are not supported.

Setup

1. Clone the repository:

git clone https://github.com/o2alexanderfedin/angular-cas-disot.git
cd angular-cas-disot

2. Install dependencies:

npm install

3. Start the development server:

npm start

4. Open your browser and navigate to http://localhost:4200/

🚦 Quick Start

Upload Content

1. Navigate to the "Upload" tab
2. Select or drag a file
3. Click "Upload" to store it in CAS
4. Copy the generated hash for future retrieval

Create DISOT Entry

1. Go to "Create Entry" tab
2. Select previously uploaded content
3. Choose entry type (CREATE/UPDATE/DELETE)
4. The system generates a key pair automatically
5. Click "Create Entry" to sign and store

Verify Entry

1. Navigate to "Verify" tab
2. Enter an entry ID
3. Click "Load & Verify"
4. View verification results and entry details

🏗 Architecture

The application follows Clean Architecture principles with clear separation of concerns:

src/app/
├── core/                 # Business logic and interfaces
│   ├── domain/          # Domain models and interfaces
│   └── services/        # Application services
├── features/            # Feature modules
│   ├── content/         # Content management components
│   └── disot/           # DISOT components
├── shared/              # Shared modules and utilities
└── app.ts              # Root component

Key Design Patterns

• Dependency Injection: Services provided at root level
• Factory Pattern: Storage provider selection at runtime
• Clean Architecture: Clear separation between UI, business logic, and infrastructure
• Content Addressing: SHA-256 based deduplication

For detailed architecture documentation, see Technical Architecture and Architecture Diagrams.

💻 Development

Development Server

npm start

Navigate to http://localhost:4200/. The app will automatically reload on changes.

Build

npm run build

Build artifacts will be stored in the dist/ directory.

Code Generation

Generate new components:

ng generate component features/my-feature --standalone

Generate new services:

ng generate service core/services/my-service

🚀 Deployment

This project uses a comprehensive CI/CD pipeline with automated deployments to GitHub Pages.

Automatic Deployments

Staging Environment

• Trigger: Push to master branch
• URL: https://o2alexanderfedin.github.io/angular-cas-disot/staging
• Purpose: Integration testing and review

Production Environment

• Trigger: Push to master branch or tagged releases
• URL: https://o2alexanderfedin.github.io/angular-cas-disot
• Purpose: Live application for end users

Local Preview Commands

# Preview staging build locally
npm run preview:staging

# Preview production build locally  
npm run preview:production

Deployment Requirements

• ✅ All CI tests must pass
• ✅ Code coverage requirements met
• ✅ Automated deployment (no manual intervention)
• ✅ Rollback capability via GitHub

📖 For detailed deployment documentation, see docs/DEPLOYMENT.md

🧪 Testing

Run Unit Tests

npm test

Executes unit tests via Karma in headless Chrome.

Test Coverage

The project maintains high test coverage with 492 tests across all components and services:

• Statements: 86.48%
• Functions: 86.88%
• Branches: 75.67%
• Lines: 87.6%
• All tests passing ✅

Test Structure

describe('CasService', () => {
  // Setup
  beforeEach(() => {
    // Test configuration
  });
  
  // Test cases
  it('should store content and return hash', async () => {
    // Test implementation
  });
});

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• Technical Architecture - Detailed system architecture and design
• API Documentation - Complete API reference for all services
• Developer Guide - Development setup and guidelines
• Architecture Overview - Visual architecture diagrams
• Component Reference - UI component documentation
• Service Reference - Service implementation details

All documentation includes code examples and visual diagrams.

🔀 GitFlow Workflow

This project uses GitFlow for version management:

Branch Structure

• master - Production-ready code
• develop - Integration branch for features
• feature/* - Feature branches
• release/* - Release preparation branches
• hotfix/* - Emergency fixes

Common Commands

Start a new feature:

git flow feature start my-feature

Finish a feature:

git flow feature finish my-feature

Start a release:

git flow release start 1.1.0

Create a hotfix:

git flow hotfix start 1.0.1

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git flow feature start amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request to develop branch

Coding Standards

• Follow Angular style guide
• Write tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

🗺 Roadmap

Version 3.0.1 (Released)

• Fixed CI test failures in IPFS integration
• Resolved race conditions in migration service
• Fixed test mocking issues
• Increased bundle size budget for Helia

Version 3.0.0 (Released) - IPFS Integration Phase 1

• IPFS storage provider with HTTP API client
• Helia browser-native IPFS implementation
• Content migration service with progress tracking
• Share link generation for IPFS gateways
• Upload queue with persistence and retry logic
• Health monitoring for IPFS nodes
• Migration UI with bulk transfer capability
• Comprehensive test coverage (402 tests)

Version 2.5.1 (Released)

• Comprehensive documentation update
• Browser storage and security documentation
• Code cleanup guide integration
• Enhanced developer guide structure

Version 2.5.0 (Released)

• Fixed staging deployment conflicts
• Enabled TypeScript strict mode
• Added dynamic code coverage display
• Improved CI/CD pipeline

Version 2.0.0 (Released)

• Complete documentation restructuring
• Numbered, audience-based folder organization
• Separated current docs from future roadmap
• Added user guides and deployment documentation
• Fixed all 390 cross-references and navigation links
• Created comprehensive changelog and resources sections

Version 1.2.0 (Released)

• Phase 1 IPFS Integration Architecture documented
• Detailed implementation guide with code examples
• Story point-based roadmap for AI development
• Security and performance considerations
• Deployment architecture for development and production

Version 1.1.4 (Released)

• Added consistent navigation emojis across all documentation
• Implemented clean, minimal navigation format with emoji arrows
• Removed redundant text labels for better readability
• Standardized navigation across 19 documentation files

Version 1.1.3 (Released)

• Fixed arrow symbols (→) causing lexical errors in Mermaid
• Applied consistent multi-line formatting for @Injectable decorators
• Quoted all node labels containing special characters
• Ensured all diagrams render correctly on GitHub

Version 1.1.2 (Released)

• Fixed Mermaid diagram rendering issues
• Quoted special characters in node labels
• Optimized diagram orientations (horizontal for flows, vertical for hierarchies)
• Fixed @Injectable, Promise<>, Map<>, and other special syntax
• Improved overall diagram readability

Version 1.1.1 (Released)

• Improved documentation clarity
• Removed color styling from diagrams
• Vertical diagram orientation
• Implementation-specific documentation
• Enhanced with visual emojis

Version 1.1.0 (Released)

• Persistent storage (IndexedDB)
• Storage provider selection
• Enhanced content preview
• Modal content selection
• Blog post support in DISOT
• Previous entry previews

Version 3.1.0 (Future)

• IPFS pinning service integration
• Advanced IPFS gateway configuration
• Content encryption for IPFS
• IPNS (InterPlanetary Name System) support
• P2P content discovery

Version 3.2.0 (Future)

• User authentication
• Permission management
• API endpoints
• WebSocket support for real-time updates

Version 4.0.0 (Long-term)

• Blockchain anchoring for IPFS hashes
• Smart contract integration
• Decentralized identity (DID) support
• Mobile applications with IPFS support
• Advanced P2P synchronization

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Angular CLI version 20.0.5
• Cryptography via Web Crypto API
• Testing with Karma and Jasmine

📞 Support

For questions and support:

• Open an issue on GitHub
• Check the documentation
• Review closed issues

---

Made with ❤️ by the CAS/DISOT team