Eloomen

A Secure, Policy-Driven Digital Vault Platform Secure your digital life. Share it on your terms.

🎯 Overview

Eloomen is a production-ready, enterprise-grade digital vault platform that enables secure, relationship-based data sharing with sophisticated time-based and conditional access policies. Built from the ground up with security-first principles, Eloomen solves critical real-world problems around digital estate planning, family data sharing, and conditional information access.

Key Differentiators

Policy-Driven Architecture: Sophisticated time-based release policies (immediate, scheduled, expiry-based, manual)
Relationship-Based Access Control: Dynamic, configurable groups with granular permissions
Multi-Type Data Support: Documents, passwords, crypto wallets, notes, and links — all encrypted
Enterprise Security: End-to-end encryption, audit logging, JWT with refresh tokens, device verification
Real-Time Notifications: Comprehensive notification system with email and in-app notifications
Production-Ready: Automated migrations, CI/CD pipelines, comprehensive error handling

🏗️ System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Next.js 16 Frontend                      │
│  React 19, TypeScript, TailwindCSS, WebCrypto API           │
│  - Client-side encryption                                   │
│  - JWT token management                                     │
│  - Real-time notifications                                  │
└───────────────────────┬─────────────────────────────────────┘
                        │ REST API (JWT Auth)
                        │ HTTPS/TLS
┌───────────────────────▼─────────────────────────────────────┐
│              ASP.NET Core 9 Backend API                     │
│  - Controllers (API Endpoints)                              │
│  - Service Layer (Business Logic)                           │
│  - Entity Framework Core (ORM)                              │
│  - Policy-based Authorization                               │
└───────┬───────────────┬───────────────┬─────────────────────┘
        │               │               │
┌───────▼────┐  ┌───────▼────┐  ┌──────▼──────────┐
│PostgreSQL  │  │  S3 Bucket  │  │  SendGrid Email │
│(Supabase)  │  │  (Storage)  │  │  (Notifications)│
│            │  │             │  │                 │
│ - 24 Tables│  │ - Documents │  │ - Transactional│
│ - Triggers │  │ - Signed URLs│ │ - Templates    │
│ - Functions│  │             │  │                 │
└────────────┘  └─────────────┘  └─────────────────┘

Detailed Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                   │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Pages      │  │ Components  │  │  Contexts    │  │  API Client  │      │
│  │  (Next.js)   │  │  (React)    │  │  (Auth)      │  │  (HTTP)      │      │
│  └──────┬───────┘  └──────┬──────┘  └──────┬──────-┘  └──────┬───────┘      │
│         │                 │                │                 │              │
│         └─────────────────┴──────────────-─┴───────────────--┘              │
│                              │ JWT Auth                                     │
└──────────────────────────────┼──────────────────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────────────────┐
│                           CONTROLLER LAYER                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │   Account    │  │    Vault     │  │  VaultItem   │  │ Notification │   │
│  │  Controller  │  │  Controller  │  │  Controller  │  │  Controller  │   │
│  └──────┬───────┘  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘   │
│         │                  │                 │                 │            │
└─────────┼──────────────────┼─────────────────┼─────────────────┼────────────┘
          │                  │                 │                 │
┌─────────▼──────────────────▼─────────────────▼─────────────────▼────────────┐
│                            SERVICE LAYER                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Token      │  │    Vault      │  │  VaultItem    │  │ Notification │ │
│  │   Service    │  │   Service     │  │   Service     │  │   Service     │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
│         │                  │                 │                 │          │
│  ┌──────▼───────┐  ┌───────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐ │
│  │   Device     │  │   Email       │  │ Encryption   │  │   S3         │ │
│  │   Service    │  │   Service     │  │   Service    │  │   Service    │ │
│  └──────────────┘  └───────────────┘  └──────────────┘  └──────────────┘ │
└─────────┬────────────────────────────────────────────────────────────────────┘
          │
┌─────────▼────────────────────────────────────────────────────────────────────┐
│                         ENTITY FRAMEWORK CORE (ORM)                           │
│  ┌──────────────────────────────────────────────────────────────────────────┐ │
│  │                    ApplicationDBContext                                 │ │
│  │  - DbSet<User>                                                          │ │
│  │  - DbSet<Vault>                                                         │ │
│  │  - DbSet<VaultItem>                                                     │ │
│  │  - DbSet<Notification>                                                  │ │
│  │  - ... (24 tables)                                                      │ │
│  └──────────────────────────────┬───────────────────────────────────────────┘ │
└─────────────────────────────────┼─────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼─────────────────────────────────────────────┐
│                           POSTGRESQL DATABASE                                 │
│  ┌──────────────────────────────────────────────────────────────────────────┐ │
│  │                        24 Database Tables                                │ │
│  │  • Users, Roles, UserRoles, UserClaims, RoleClaims                      │ │
│  │  • UserDevices, RefreshTokens, VerificationCodes                         │ │
│  │  • Vaults, VaultMembers, VaultInvites, VaultPolicies                   │ │
│  │  • VaultItems, VaultItemVisibilities                                   │ │
│  │  • VaultDocuments, VaultPasswords, VaultNotes                           │ │
│  │  • VaultLinks, VaultCryptoWallets                                      │ │
│  │  • VaultLogs, AccountLogs, Notifications                               │ │
│  │  • UserLogins, UserTokens                                              │ │
│  └──────────────────────────────┬───────────────────────────────────────────┘ │
│                                 │                                             │
│  ┌──────────────────────────────▼──────────────────────────────────────────┐ │
│  │                    PostgreSQL Triggers & Functions                      │ │
│  │  • notify_vault_released() - Auto-notify on vault release              │ │
│  │  • vault_release_notification_trigger - Monitors ReleaseStatus changes │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────┘

Data Flow Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         NOTIFICATION FLOW                                    │
│                                                                              │
│  Event Triggered (Vault Release, Item Edit, Invite, etc.)                  │
│         │                                                                    │
│         ├──────────────────────────────────────────────────────┐            │
│         │                                                        │            │
│  ┌──────▼──────────┐                                  ┌────────▼──────┐   │
│  │ Service Layer    │                                  │ PostgreSQL    │   │
│  │ (Business Logic) │                                  │ Trigger       │   │
│  └──────┬───────────┘                                  └────────┬───────┘   │
│         │                                                        │            │
│  ┌──────▼──────────┐                                  ┌────────▼──────┐   │
│  │ Email Service    │                                  │ Notifications  │   │
│  │ (SendGrid)       │                                  │ Table         │   │
│  │                  │                                  └────────┬───────┘   │
│  │ • Send Email     │                                           │            │
│  │ • HTML Templates│                                           │            │
│  └──────────────────┘                                  ┌────────▼──────┐   │
│                                                        │ Notification  │   │
│                                                        │ Service       │   │
│                                                        │ (Create/Read) │   │
│                                                        └────────┬───────┘   │
│                                                                 │            │
│                                                        ┌────────▼──────┐   │
│                                                        │ Frontend      │   │
│                                                        │ (Real-time UI)│   │
│                                                        └───────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

Service Layer Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                            SERVICE INTERFACES                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ ITokenService│  │ IVaultService│  │IVaultItem     │  │INotification │   │
│  │              │  │              │  │Service        │  │Service       │   │
│  └──────┬───────┘  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘   │
│         │                  │                 │                 │            │
│  ┌──────▼───────┐  ┌───────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐ │
│  │ TokenService  │  │  VaultService  │  │VaultItem     │  │Notification │ │
│  │              │  │                │  │Service       │  │Service      │ │
│  │ • JWT Gen    │  │ • CRUD Ops     │  │ • CRUD Ops   │  │ • Create     │ │
│  │ • Refresh    │  │ • Policy Mgmt  │  │ • Encryption │  │ • Mark Read  │ │
│  │ • Validation │  │ • Invites      │  │ • Permissions│  │ • Delete     │ │
│  │              │  │ • Members       │  │ • S3 Upload  │  │ • Query      │ │
│  └──────────────┘  └───────┬────────┘  └──────┬───────┘  └──────────────┘ │
│                            │                  │                           │
│  ┌─────────────────────────▼──────────────────▼───────────────────────────┐ │
│  │                    SUPPORTING SERVICES                                 │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│ │
│  │  │ IEmailService│  │IEncryption  │  │  IS3Service  │  │IDeviceService││ │
│  │  │              │  │Service      │  │              │  │              ││ │
│  │  │ • SendGrid   │  │ • AES-256   │  │ • Upload     │  │ • Fingerprint││ │
│  │  │ • Templates  │  │ • Encrypt   │  │ • Download   │  │ • Verify     ││ │
│  │  │ • Notify     │  │ • Decrypt   │  │ • Delete     │  │ • Manage     ││ │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘│ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────┘

Technical Stack Deep Dive

Frontend Stack

Framework: Next.js 16.1.1 (App Router, Server Components)
Language: TypeScript 5.0+ (strict mode)
UI: React 19.2.3, TailwindCSS 4.0
State Management: React Context API, Custom hooks
Authentication: JWT with automatic token refresh
Encryption: WebCrypto API for client-side encryption
HTTP Client: Custom API client with retry logic and error handling
Notifications: Real-time notification system with polling and badge counts

Backend Stack

Framework: ASP.NET Core 9.0
ORM: Entity Framework Core 9.0 (Code-First migrations)
Database: PostgreSQL 15+ (via Supabase)
Authentication: ASP.NET Core Identity + Custom JWT implementation
Authorization: Policy-based with role hierarchy (Owner → Admin → Member)
File Storage: S3 bucket for document storage
Email: SendGrid integration for transactional emails
API Documentation: Swagger/OpenAPI
Notifications: In-app notification system with PostgreSQL triggers

Infrastructure & DevOps

Database: Supabase (PostgreSQL + Storage)
Object Storage: S3 bucket
CI/CD: GitHub Actions (build, test, deploy)
Migrations: Automatic EF Core migrations on startup
Logging: Structured logging with ILogger
Error Handling: Global exception handling, custom error responses
Database Triggers: PostgreSQL functions for automated notifications

🔐 Security Architecture

Authentication & Authorization

Multi-Layer Security Model:

JWT Authentication
- Short-lived access tokens (15 minutes)
- Long-lived refresh tokens (stored in HTTP-only cookies)
- Automatic token rotation on refresh
- Security stamp validation for token revocation
Device Verification
- Device fingerprinting for new device detection
- Email-based device verification codes
- Device management dashboard
Role-Based Access Control (RBAC)
- Owner: Full control (create, edit, delete, manage members, transfer ownership)
- Admin: Manage items and members (cannot delete vault or transfer ownership)
- Member: View and edit items (permission-based)
Policy-Based Access Control
- Vault-level policies override member access
- Time-based release policies
- Expiry-based access revocation
- Manual release triggers

Data Encryption

At Rest: All sensitive data encrypted before database storage
In Transit: HTTPS/TLS for all API communications
Client-Side: WebCrypto API for encryption before transmission
Secrets: Passwords, crypto keys, and sensitive notes encrypted with AES-256

Audit & Compliance

Comprehensive Audit Logging: All vault operations logged (create, update, delete, invite, member changes)
Account Activity Logs: User authentication, device changes, profile updates
Immutable Logs: Timestamped, user-attributed audit trail
Data Retention: Configurable retention policies
Change Tracking: Detailed field-level change tracking for vault items

📊 Database Schema

Complete PostgreSQL Tables (24 Tables)

The application uses 24 PostgreSQL tables organized into the following categories:

Identity & Authentication Tables (7 tables)

Users - Core user accounts with email, username, security stamps
Roles - System roles (Admin, User)
UserRoles - Many-to-many relationship between users and roles
UserClaims - Custom claims for users
RoleClaims - Custom claims for roles
UserLogins - External login providers
UserTokens - External authentication tokens

Device & Session Management (3 tables)

UserDevices - Registered devices with fingerprinting
RefreshTokens - JWT refresh tokens linked to devices
VerificationCodes - Email/device verification codes

Vault Core Tables (4 tables)

Vaults - Main vault entities with owner relationships
VaultMembers - Vault membership with privileges (Owner/Admin/Member)
VaultInvites - Invitation system with tokens and expiration
VaultPolicies - Policy configuration (Immediate/TimeBased/ExpiryBased/ManualRelease)

Vault Items & Content (7 tables)

VaultItems - Base vault item entity (polymorphic)
VaultItemVisibilities - Granular permissions per item per member
VaultDocuments - Document items with S3 object keys
VaultPasswords - Password items (encrypted)
VaultNotes - Note items (encrypted)
VaultLinks - Link/bookmark items
VaultCryptoWallets - Cryptocurrency wallet items (encrypted)

Audit & Notifications (3 tables)

VaultLogs - Comprehensive vault operation audit logs
AccountLogs - User account activity logs
Notifications - In-app notification system

Entity Relationship Diagram

Users (1) ──────< (N) Vaults (Owner)
  │                    │
  │                    ├──< (N) VaultMembers >── (N) Users
  │                    │
  │                    ├──< (N) VaultInvites
  │                    │
  │                    ├──< (1) VaultPolicies
  │                    │
  │                    └──< (N) VaultItems
  │                           │
  │                           ├──< (1) VaultDocuments
  │                           ├──< (1) VaultPasswords
  │                           ├──< (1) VaultNotes
  │                           ├──< (1) VaultLinks
  │                           ├──< (1) VaultCryptoWallets
  │                           │
  │                           └──< (N) VaultItemVisibilities >── (N) VaultMembers
  │
  ├──< (N) UserDevices
  │      └──< (N) RefreshTokens
  │
  ├──< (N) VerificationCodes
  ├──< (N) AccountLogs
  └──< (N) Notifications

VaultPolicies ──> PostgreSQL Trigger ──> Notifications (Auto-create on release)

Key Design Decisions

Soft Deletes: Vaults and items support 30-day recovery window
Cascade Deletes: Proper foreign key constraints with cascade rules
Indexing: Optimized indexes on frequently queried fields (userId, vaultId, status, timestamps)
Transactions: Critical operations wrapped in database transactions
Migration Strategy: Code-first migrations with automatic application
Database Triggers: PostgreSQL functions for automated notification creation on vault release
Polymorphic Items: Single VaultItems table with one-to-one relationships to specific item types

🚀 Key Features & Implementation Highlights

1. Policy Engine

Sophisticated policy system supporting multiple release strategies:

Immediate: Instant access upon vault creation
TimeBased: Scheduled release at a future date/time
ExpiryBased: Access expires after a set date
ManualRelease: Requires explicit owner action

Implementation: Policy evaluation runs on every vault access, automatically updating release status based on current time and policy rules. PostgreSQL triggers automatically create notifications when vaults are released.

2. Granular Item Permissions

Each vault item can have different visibility rules per member:

View: Read-only access
Edit: Full edit capabilities
Inherit: Default vault-level permissions

Implementation: VaultItemVisibility junction table enables fine-grained access control without performance overhead. Owners always have Edit permission and are excluded from visibility checks.

3. Invite System

Robust invitation workflow with:

Email-based invitations with secure tokens
Expiration handling (default 7 days, configurable)
Status tracking (Pending → Sent → Accepted/Cancelled/Expired)
Automatic member creation on acceptance
Resend and cancel capabilities
Email notifications to vault owner when invites are sent
Notifications to both inviter and invitee when invites expire

Security: Tokens hashed with SHA-256 before storage, never stored in plaintext.

4. File Upload & Storage

S3 Bucket Integration: Secure document storage with signed URLs
Signed URLs: Time-limited download URLs for secure file access
Metadata Tracking: File size, MIME type, original filename
Cleanup: Automatic file deletion on item/vault deletion

5. Notification System

Comprehensive notification system with multiple channels:

In-App Notifications: Real-time notification center with unread badges
Email Notifications: SendGrid integration for critical events
PostgreSQL Triggers: Automated notification creation on vault release
Notification Types:
- Vault released
- Vault policy changed
- Vault deleted
- Vault item edited/deleted (to owner)
- Invite sent/accepted/expired
- Password changed
- Account deleted

Implementation: Notifications are created both programmatically in services and automatically via database triggers for vault release events.

6. Email Notification System

Comprehensive email notification system covering:

Account Events: Email verification, password changes, account deletion
Vault Events: Vault released, policy changed, vault deleted
Item Events: Item edited/deleted by other members (notifies owner)
Invite Events: Invite sent, accepted, expired
Security Events: Device verification, password reset

Implementation: SendGrid service with HTML email templates, dark mode styling, and professional branding.

7. Audit Logging

Comprehensive audit trail:

VaultLogs: All vault operations (create, update, delete, invite, member changes)
AccountLogs: User authentication, device changes, profile updates
Change Tracking: Field-level change tracking for vault items (title, description, permissions, etc.)
Immutable Logs: Timestamped, user-attributed audit trail

8. Error Handling & Resilience

Custom Error Classes: SessionExpiredError for graceful auth failures
Retry Logic: Automatic token refresh on 401 responses
User-Friendly Messages: Transformed technical errors into actionable user feedback
Logging: Comprehensive error logging with context for debugging

🧪 Development & Testing

Code Quality

TypeScript: Strict mode enabled, full type safety
ESLint: Next.js recommended rules
Code Organization: Feature-based folder structure
Separation of Concerns: Clear boundaries between UI, business logic, and data access

API Design

RESTful Principles: Standard HTTP methods and status codes
DTO Pattern: Separate request/response DTOs for type safety
Validation: Model validation with ASP.NET Core Data Annotations
Error Responses: Consistent error response format

Performance Optimizations

Database Queries: Eager loading with .Include() to prevent N+1 queries
Indexing: Comprehensive indexes on foreign keys, status fields, and timestamps
Pagination Ready: Architecture supports pagination (future enhancement)
Caching Strategy: Ready for Redis integration (future)
Frontend: Code splitting, lazy loading, optimized bundle size
Notification Polling: Efficient 30-second polling for new notifications

🧪 Testing

Test Setup

The project includes comprehensive backend testing using xUnit and Moq for .NET 9.0.

Prerequisites

.NET 9 SDK (required for running tests)
PostgreSQL (for integration tests, can use in-memory database for unit tests)

Test Project Structure

server/
├── Tests/
│   ├── Controllers/          # Controller integration tests
│   │   ├── AccountControllerTests.cs
│   │   ├── VaultControllerTests.cs
│   │   ├── VaultItemControllerTests.cs
│   │   ├── NotificationControllerTests.cs
│   │   ├── ContactControllerTests.cs
│   │   └── HealthControllerTests.cs
│   ├── Services/             # Service layer unit tests
│   │   ├── TokenServiceTests.cs
│   │   ├── VaultServiceTests.cs
│   │   ├── VaultItemServiceTests.cs
│   │   ├── NotificationServiceTests.cs
│   │   ├── EncryptionServiceTests.cs
│   │   ├── DeviceServiceTests.cs
│   │   └── VaultServiceExtendedTests.cs
│   ├── Helpers/              # Test utilities and helpers
│   │   └── TestHelpers.cs
│   └── server.Tests.csproj   # Test project file

Running Tests

Run All Tests

cd server
dotnet test Tests/server.Tests.csproj --configuration Release --verbosity normal

Run Tests with Coverage

cd server
dotnet test Tests/server.Tests.csproj \
  --configuration Release \
  --collect:"XPlat Code Coverage" \
  --results-directory:./coverage

Run Specific Test Class

dotnet test Tests/server.Tests.csproj --filter "FullyQualifiedName~AccountControllerTests"

Run Specific Test Method

dotnet test Tests/server.Tests.csproj --filter "FullyQualifiedName~AccountControllerTests.Register_WithValidData_CreatesUser"

Test Results

Current Test Status

✅ All Tests Passing: 117 tests, 0 failures

Test Coverage by Category

Controller Tests (6 test classes, ~40 tests)

✅ AccountControllerTests - Authentication, registration, profile management
✅ VaultControllerTests - Vault CRUD, member management, invites, policies
✅ VaultItemControllerTests - Item CRUD, permissions, restore operations
✅ NotificationControllerTests - Notification retrieval, marking as read, deletion
✅ ContactControllerTests - Contact form submission
✅ HealthControllerTests - Health check endpoints

Service Tests (8 test classes, ~77 tests)

✅ TokenServiceTests - JWT token generation, validation, refresh tokens
✅ VaultServiceTests - Vault business logic, permissions, CRUD operations
✅ VaultServiceExtendedTests - Advanced vault operations (invites, transfers, policies)
✅ VaultItemServiceTests - Item operations, permissions, encryption
✅ VaultItemServiceExtendedTests - Advanced item operations (restore, permissions)
✅ NotificationServiceTests - Notification creation, retrieval, updates
✅ EncryptionServiceTests - AES-256 encryption/decryption, Unicode support
✅ DeviceServiceTests - Device fingerprinting, verification, management

CI/CD Integration

Tests are automatically run in GitHub Actions on every push and pull request:

# .github/workflows/ci.yml
- name: Run tests
  run: dotnet test server/Tests/server.Tests.csproj --no-restore --configuration Release --verbosity normal

Test Execution in CI

Trigger: Push to main, develop, master branches or pull requests
Environment: Ubuntu Latest with .NET 9.0.x
Test Results: Uploaded as artifacts for review
Status: All tests must pass for CI to succeed

Test Architecture

Test Patterns Used

Arrange-Act-Assert (AAA): Standard test structure
Mocking: Moq framework for dependencies (database, external services)
In-Memory Database: EF Core InMemory provider for fast unit tests
Test Fixtures: Reusable test data and setup helpers
Integration Tests: Full controller tests with mocked services

Example Test Structure

[Fact]
public async Task Register_WithValidData_CreatesUser()
{
    // Arrange
    var registerDto = new RegisterDTO { /* ... */ };

    // Act
    var result = await _controller.Register(registerDto);

    // Assert
    Assert.NotNull(result);
    Assert.Equal(200, ((ObjectResult)result).StatusCode);
}

Test Data Management

Test Helpers: TestHelpers.cs provides utilities for creating test data
Isolated Tests: Each test is independent with its own database context
Cleanup: Automatic cleanup after each test execution
Test Data: Realistic test scenarios covering edge cases

Coverage Goals

✅ Controllers: 100% endpoint coverage
✅ Services: Core business logic fully tested
✅ Critical Paths: Authentication, authorization, encryption
🔄 Integration Tests: API endpoint integration testing
🔄 E2E Tests: Full user workflow testing (planned)

Running Tests Locally Before Push

Always run tests locally before pushing to ensure CI passes:

# Run all tests
cd server
dotnet test Tests/server.Tests.csproj --configuration Release

# Expected output: All 117 tests passing ✅

📦 Project Structure

Eloomen/
├── client/                          # Next.js frontend
│   ├── app/                        # App Router pages
│   │   ├── components/            # Reusable React components
│   │   │   ├── ContactModal.tsx
│   │   │   ├── CreateVaultItemModal.tsx
│   │   │   └── NotificationsModal.tsx
│   │   ├── contexts/              # React Context providers
│   │   │   └── AuthContext.tsx
│   │   ├── lib/                   # Utilities, API client
│   │   │   └── api.ts            # API client with JWT handling
│   │   ├── dashboard/             # Dashboard page
│   │   ├── vaults/[id]/          # Vault detail page
│   │   ├── account/              # Account management
│   │   ├── login/                # Authentication pages
│   │   └── [other routes]/
│   ├── public/                    # Static assets
│   │   └── icon.png             # Logo
│   └── package.json
│
├── server/                         # ASP.NET Core backend
│   ├── Controllers/              # API endpoints
│   │   ├── AccountController.cs
│   │   ├── VaultController.cs
│   │   ├── VaultItemController.cs
│   │   ├── NotificationController.cs
│   │   └── ContactController.cs
│   ├── Services/                 # Business logic layer
│   │   ├── TokenService.cs
│   │   ├── VaultService.cs
│   │   ├── VaultItemService.cs
│   │   ├── NotificationService.cs
│   │   ├── EmailService.cs
│   │   ├── EncryptionService.cs
│   │   ├── S3Service.cs
│   │   └── DeviceService.cs
│   ├── Interfaces/               # Service contracts
│   │   ├── ITokenService.cs
│   │   ├── IVaultService.cs
│   │   ├── IVaultItemService.cs
│   │   ├── INotificationService.cs
│   │   ├── IEmailService.cs
│   │   ├── IEncryptionService.cs
│   │   ├── IS3Service.cs
│   │   └── IDeviceService.cs
│   ├── Models/                   # Entity models (24 tables)
│   │   ├── User.cs
│   │   ├── Vault.cs
│   │   ├── VaultItem.cs
│   │   ├── Notification.cs
│   │   └── [other models]
│   ├── Dtos/                     # Data transfer objects
│   │   ├── Account/
│   │   ├── Vault/
│   │   ├── VaultItem/
│   │   └── Notification/
│   ├── Data/                     # DbContext, migrations
│   │   ├── ApplicationDBContext.cs
│   │   └── Migrations/
│   │       └── [migration files including triggers]
│   └── Program.cs                # Application startup
│
└── README.md

🚀 Getting Started

Prerequisites

Node.js 20+ and npm
.NET 9 SDK
PostgreSQL 15+ (or Supabase account)
AWS S3 bucket (for file storage)
SendGrid account (for emails)

Environment Setup

Backend Configuration (server/appsettings.json):

{
  "ConnectionStrings": {
    "Default": "PostgreSQL connection string"
  },
  "Jwt": {
    "Issuer": "Eloomen",
    "Audience": "EloomenUsers",
    "SigningKey": "your-secret-key"
  },
  "S3": {
    "Endpoint": "your-s3-endpoint",
    "AccessKey": "your-access-key",
    "SecretKey": "your-secret-key",
    "BucketName": "your-bucket"
  },
  "SendGrid": {
    "ApiKey": "your-sendgrid-api-key",
    "FromEmail": "noreply@eloomen.com",
    "FromName": "Eloomen"
  },
  "App": {
    "BaseUrl": "http://localhost:3000"
  }
}

Frontend Configuration (.env.local):

NEXT_PUBLIC_API_URL=http://localhost:5000/api

Running Locally

Run both server and client separately in different terminals:

# Backend
cd server
dotnet restore
dotnet watch run

# Frontend (new terminal)
cd client
npm install
npm run dev

🐳 Docker Setup

The project includes a complete Docker setup with hot reload for both frontend and backend, making it easy to run the entire application with a single command.

Prerequisites

Docker and Docker Compose installed
.env file created in the root directory (see setup below)

Quick Start

Create a .env file in the root directory of the project.

Option A: Copy from appsettings.development.json

If you already have server/appsettings.development.json configured, you can create the .env file by converting the JSON structure to environment variables. Use double underscores (__) for nested configuration keys.

Option B: Create manually

The .env file should contain all environment variables matching the structure of server/appsettings.development.json. Use double underscores (__) for nested configuration keys.

Example .env file:

# Database Connection String
ConnectionStrings__Default=User Id=postgres.xxx;Password=xxx;Server=xxx;Port=5432;Database=postgres

# JWT Configuration
Jwt__Issuer=http://localhost:3000
Jwt__Audience=http://localhost:3001
Jwt__SigningKey=your-secret-signing-key-here
Jwt__AccessTokenMinutes=15
Jwt__RefreshTokenDays=30

# SendGrid Configuration
SendGrid__ApiKey=SG.xxx
SendGrid__FromEmail=support@eloomen.com
SendGrid__FromName=Eloomen
SendGrid__AdminEmail=your-admin-email@example.com

# App Configuration
App__BaseUrl=http://localhost:3001
App__EmailVerificationPath=/verify-email
App__DeviceVerificationPath=/verify-device
App__PasswordResetPath=/reset-password
App__VerificationCodeExpiration__EmailVerificationMinutes=1440
App__VerificationCodeExpiration__DeviceVerificationMinutes=60
App__VerificationCodeExpiration__PasswordResetMinutes=60

# S3 / Cloudflare R2 Configuration
S3__BucketName=eloomen-dev
S3__BaseUrl=https://xxx.r2.cloudflarestorage.com
S3__Endpoint=https://xxx.r2.cloudflarestorage.com
S3__AccessKeyId=xxx
S3__SecretAccessKey=xxx

# Frontend Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Important Notes:

The .env file is already in .gitignore and will not be committed to the repository
Variable names use __ (double underscore) for nested configuration (e.g., ConnectionStrings__Default, Jwt__Issuer)
Copy values from server/appsettings.development.json and convert the JSON structure to environment variable format
For nested objects, use __ to separate levels (e.g., App__VerificationCodeExpiration__EmailVerificationMinutes)

Start all services with Docker Compose:
```
docker-compose up
```
This will:
- Build and start both frontend and backend services
- Enable hot reload for both services (changes are reflected immediately)
- Expose frontend on http://localhost:3001
- Expose backend on http://localhost:3000
- Automatically run database migrations on backend startup
- Load all environment variables from the .env file

Services

Backend (ASP.NET Core)

Port: 3000
Hot Reload: Enabled via dotnet watch
Environment: Development
Database: Automatically runs migrations on startup
Swagger: Available at http://localhost:3000/swagger

Frontend (Next.js)

Port: 3001
Hot Reload: Enabled via Next.js dev mode
API URL: http://localhost:3000/api

Docker Commands

# Start services
docker-compose up

# Start in detached mode (background)
docker-compose up -d

# Stop services
docker-compose down

# Rebuild after dependency changes
docker-compose build
docker-compose up

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend
docker-compose logs -f frontend

Hot Reload

Both services support hot reload out of the box:

Backend: Changes to .cs files automatically trigger dotnet watch to rebuild and restart
Frontend: Changes to .tsx, .ts, and .css files are automatically reflected in the browser

Source code is mounted as volumes, so you can edit files directly and see changes immediately.

Environment Variables

All environment variables are loaded from the .env file in the root directory. The docker-compose.yml uses env_file: - .env to automatically load all variables into both services.

Key Points:

The .env file must be created in the root directory (same level as docker-compose.yml)
Variable names must match the structure of appsettings.development.json using __ for nesting
The .env file is already in .gitignore and will not be committed to the repository
Both backend and frontend services read from the same .env file
Environment variables override appsettings.development.json when set

Converting from appsettings.development.json to .env:

JSON Structure	Environment Variable
`ConnectionStrings.Default`	`ConnectionStrings__Default`
`Jwt.Issuer`	`Jwt__Issuer`
`App.VerificationCodeExpiration.EmailVerificationMinutes`	`App__VerificationCodeExpiration__EmailVerificationMinutes`

Quick Reference:

Replace dots (.) with double underscores (__)
Keep the same structure and nesting
All string values should be unquoted
Copy exact values from appsettings.development.json

Troubleshooting

Services won't start

Ensure Docker and Docker Compose are installed and running
Check that all required environment variables are set in .env
Verify ports 3000 and 3001 are not already in use

Hot reload not working

Ensure source code volumes are properly mounted (check docker-compose.yml)
Try rebuilding containers: docker-compose build --no-cache

Database connection issues

Verify ConnectionStrings__Default in .env is correct
Check that your database is accessible from Docker containers
For local PostgreSQL, use host.docker.internal instead of localhost
Ensure the connection string format matches: User Id=xxx;Password=xxx;Server=xxx;Port=5432;Database=postgres

Frontend can't connect to backend

Verify NEXT_PUBLIC_API_URL in .env matches backend URL
Check that both containers are on the same Docker network
Ensure backend is running and accessible on port 3000

🔄 CI/CD Pipeline

GitHub Actions Workflow:

Backend Tests: Run 117 unit and integration tests
- Controller tests (Account, Vault, VaultItem, Notification, Contact, Health)
- Service tests (Token, Vault, VaultItem, Notification, Encryption, Device)
- Test results uploaded as artifacts
Frontend Build & Lint: Build Next.js app and run ESLint
Build: Compile .NET backend, build Next.js frontend
Migrations: Automatic database migrations on startup (Railway)
Deploy: Automated deployment via Railway and Vercel (connected via GitHub)

📈 Performance Metrics

API Response Time: < 200ms (p95) for standard operations
Database Queries: Optimized with proper indexing
Frontend Bundle: Code-split, lazy-loaded components
File Upload: Streaming uploads for large files
Notification Polling: 30-second intervals for efficient updates

🔮 Future Enhancements

Planned Features

Mobile Apps: Native iOS and Android applications
Hardware Key Support: FIDO2/WebAuthn integration
Encrypted Search: Search over encrypted data
Enterprise Plans: Team management, SSO, advanced policies
Advanced Analytics: Usage dashboards, access reports
Real-time Updates: WebSocket support for live notifications

Technical Debt & Improvements

Unit test coverage (backend services) - ✅ 117 tests implemented
Integration tests (API endpoints) - ✅ Controller tests implemented
E2E tests (Playwright/Cypress)
Performance monitoring (Application Insights)
Rate limiting (API throttling)
Caching layer (Redis)
WebSocket for real-time notifications

🤝 Contributing

This is a personal project showcasing full-stack development capabilities. Key areas of focus:

Security: Industry-standard encryption and authentication
Scalability: Architecture designed for growth
Maintainability: Clean code, clear documentation
User Experience: Intuitive UI, responsive design

📄 License

👨‍💻 Engineering Highlights

Technical Achievements

✅ Full-Stack Development: End-to-end implementation from database to UI
✅ Security-First Design: Multi-layer security with encryption, RBAC, and audit logging
✅ Scalable Architecture: Microservices-ready, cloud-native design
✅ Modern Tech Stack: Latest versions of Next.js, .NET, React, TypeScript
✅ Production Practices: CI/CD, automated migrations, error handling, logging
✅ Complex Business Logic: Policy engine, time-based access, granular permissions
✅ API Design: RESTful, well-documented, type-safe
✅ Database Design: Normalized schema, proper relationships, migrations, triggers
✅ Notification System: Comprehensive in-app and email notifications
✅ Change Tracking: Detailed field-level change tracking for audit trails
✅ Test Coverage: 117 comprehensive unit and integration tests

Skills Demonstrated

Backend: ASP.NET Core, Entity Framework Core, PostgreSQL, RESTful APIs
Frontend: Next.js, React, TypeScript, TailwindCSS, State Management
Security: JWT, Encryption, RBAC, Audit Logging, Device Verification
DevOps: GitHub Actions, Docker, Database Migrations
Architecture: Clean Architecture, DTO Pattern, Service Layer Pattern
Database: PostgreSQL triggers, functions, complex relationships
Problem Solving: Complex policy engine, granular permissions, time-based access
Integration: SendGrid, S3, Supabase

Built with ❤️ using Next.js, ASP.NET Core, and PostgreSQL

Report Bug · Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 98 Commits
.github/workflows		.github/workflows
client		client
server		server
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

License

hasanpeal/Eloomen

Folders and files

Latest commit

History

Repository files navigation

Eloomen

🎯 Overview

Key Differentiators

🏗️ System Architecture

High-Level Architecture

Detailed Architecture Diagram

Data Flow Architecture

Service Layer Architecture

Technical Stack Deep Dive

Frontend Stack

Backend Stack

Infrastructure & DevOps

🔐 Security Architecture

Authentication & Authorization

Data Encryption

Audit & Compliance

📊 Database Schema

Complete PostgreSQL Tables (24 Tables)

Identity & Authentication Tables (7 tables)

Device & Session Management (3 tables)

Vault Core Tables (4 tables)

Vault Items & Content (7 tables)

Audit & Notifications (3 tables)

Entity Relationship Diagram

Key Design Decisions

🚀 Key Features & Implementation Highlights

1. Policy Engine

2. Granular Item Permissions

3. Invite System

4. File Upload & Storage

5. Notification System

6. Email Notification System

7. Audit Logging

8. Error Handling & Resilience

🧪 Development & Testing

Code Quality

API Design

Performance Optimizations

🧪 Testing

Test Setup

Prerequisites

Test Project Structure

Running Tests

Run All Tests

Run Tests with Coverage

Run Specific Test Class

Run Specific Test Method

Test Results

Current Test Status

Test Coverage by Category

CI/CD Integration

Test Execution in CI

Test Architecture

Test Patterns Used

Example Test Structure

Test Data Management

Coverage Goals

Running Tests Locally Before Push

📦 Project Structure

🚀 Getting Started

Prerequisites

Environment Setup

Running Locally

🐳 Docker Setup

Prerequisites

Quick Start

Services

Backend (ASP.NET Core)

Frontend (Next.js)

Docker Commands

Hot Reload

Environment Variables

Troubleshooting

Services won't start