Notes App - Angular Learning Repository

Educational Reference: Clean 3-layer architecture with modern Angular signals, multiple production-ready domains (Tasks, Logging, Balance Sheet, Workflow Engine), and comprehensive testing.

📚 Purpose

This is a learning-focused repository demonstrating production-ready Angular patterns through iterative development. Built as a reference for clean architecture, modern signals, and domain-driven design.

🎯 What You'll Learn

Architecture Patterns

✅ 3-layer architecture (Data → Service → Presentation)
✅ Domain-driven structure (vertical slices)
✅ Separation of concerns
✅ Repository pattern for data abstraction

Modern Angular (v16+)

✅ Signals for reactive state management
✅ Computed signals for derived state
✅ Standalone components
✅ Signal-based component communication
✅ Effect for reactive side effects

Advanced Features

✅ Audit trail / history tracking
✅ System-wide logging with pagination, search, filtering
✅ Soft delete pattern
✅ Time-travel debugging (revert to previous state)
✅ Multi-view presentation (List, Kanban, Metrics, Logs)
✅ Drag-and-drop with Angular CDK
✅ Multi-select with checkboxes
✅ Delta-based change tracking (only log what changed)
✅ Financial balance sheet tracking with net worth calculation
✅ Enterprise workflow engine with status tracking and templates

Production Patterns

✅ Type-safe CRUD operations (zero any casts)
✅ Strict immutability enforcement
✅ Robust error handling (quota exceeded, corrupted data)
✅ Proper object comparison (no JSON.stringify)
✅ Unidirectional data flow (no two-way binding)
✅ Single Responsibility Principle (SRP)
✅ Centralized constants (no magic strings)
✅ SSR-friendly (platform checks)
✅ Date serialization handling
✅ Enum-driven type safety
✅ Comprehensive test coverage (72 passing tests for logging domain)

🏗️ Architecture

Task Domain

src/app/domains/task/
├── data/
│   └── task.repository.ts          # Data persistence with error handling
├── service/
│   ├── task.service.ts             # CRUD orchestration + logging integration
│   ├── taskState.service.ts        # Reactive state + business logic
│   └── taskHistory.service.ts      # History management (SRP)
├── presentation/
│   ├── task/                       # Container component
│   ├── task-add/                   # Form component (delta-based updates)
│   ├── task-list/                  # List view with filters
│   └── task-kanban/                # Drag-drop board (dumb layer)
├── task.model.ts                   # Domain models & types
└── task.constants.ts               # Centralized constants

Logging Domain

src/app/domains/logging/
├── data/
│   ├── logging.repository.ts          # Log persistence with delete/clear (localStorage)
│   └── logging.repository.spec.ts     # 20 tests (CRUD, SSR, errors)
├── service/
│   ├── logging.service.ts             # Complete CRUD with auto-initialization
│   ├── logging.service.spec.ts        # 14 tests (CRUD, ID generation, integration)
│   ├── loggingState.service.ts        # Reactive state with auto-sorting
│   └── loggingState.service.spec.ts   # 13 tests (signals, sorting, reactivity)
├── presentation/
│   └── logging-list/
│       ├── logging-list.component.ts  # Log viewer with pagination, search, filters
│       ├── logging-list.component.html # Responsive UI with delete/clear actions
│       ├── logging-list.component.scss # Material Design styling
│       └── logging-list.component.spec.ts # 25 tests (filtering, pagination, CRUD)
└── logging.model.ts                   # Type-safe log models (Info, Warn, Error)

Balance Sheet Domain

src/app/domains/balance-sheet/
├── data/
│   └── balance-sheet.repository.ts    # Financial data persistence
├── service/
│   ├── balance-sheet.service.ts       # Balance sheet CRUD orchestration
│   └── balanceSheetState.service.ts   # Reactive financial state management
├── presentation/
│   ├── account-list/                  # Asset/liability account management
│   ├── balance-form/                  # Record account balances
│   ├── balance-history/               # Historical balance tracking
│   └── balance-sheet-view/            # Net worth dashboard
└── balance-sheet.model.ts             # Financial domain models

Workflow Engine Domain

src/app/domains/workflow/
├── data/
│   └── workflow.repository.ts         # Workflow persistence
├── service/
│   ├── workflow.service.ts            # Workflow orchestration
│   └── workflowState.service.ts       # Reactive workflow state
├── presentation/
│   ├── instance-tracker/              # Active workflow instances
│   └── template-library/              # Reusable workflow templates
└── workflow.model.ts                  # Workflow domain models

Shared Utilities

src/app/shared/utils/
├── date-formatter.util.ts          # Date formatting (timezone-aware)
├── json-serialization.util.ts      # Date serialization
└── object-comparison.util.ts       # Deep equality (no JSON.stringify)

Layer Responsibilities

Layer	Purpose	Technologies
Data	Persistence abstraction	localStorage, JSON serialization
Service	Business logic & state	Signals, computed signals, CRUD
Presentation	UI components	Standalone components, CDK

⚡ Recent Architectural Improvements

Logging Domain P1 Enhancements (Latest)

The logging domain received comprehensive UI/UX polish and architectural improvements:

1. Tab-Based Level Filter with Counts

Visual tabs replace dropdown: All (11) | Info (9) | Warn (2)
Context-aware counts based on search results only (not affected by level selection)
Disabled tabs when count is 0 for better affordance
Color-coded tabs matching log levels (blue/orange/red)

2. Convenience Logging API

New methods: logInfo(), logWarn(), logError()
Cleaner call sites: this.loggingService.logInfo('Task created', { context, data })
No need to import LogLevel enum in other domains
All Task and Balance Sheet domains updated to use new API

3. Production-Ready Features

Max log retention (1000 logs) with automatic pruning of oldest
Relative timestamps ("Just now", "2 minutes ago") with absolute tooltip on hover
Data expansion preview hints ({3 fields}, [5 items])
Search icon + clear button for better affordance
Contextual empty states with icons and helpful messages

4. Performance Optimizations

TrackBy function for efficient list rendering
Single-pass counting algorithm for log level distribution
Proper computed signal chain: logs → searchFilteredLogs → filteredLogs → paginatedLogs

5. Smooth Animations

CSS transitions for expand/collapse (0.3s ease-out)
Animates: max-height, opacity, margin, padding

6. Architectural Clarity

Counts computed from search-filtered logs (presentation logic stays in component)
Level filter is view-only selection, doesn't affect tab counts
Clear separation: domain layer owns raw state, presentation owns filtered views

Logging Domain P0 Enhancements

The logging domain received critical production-ready upgrades:

1. Complete CRUD Operations

Added delete() method across all layers (repository → state → service)
Added clear() method for bulk deletion
Proper orchestration: persist to storage first, then update signal state
Memory leak prevention: cleanup of UI expansion state

2. Pagination System

Configurable page size (default 5 logs per page)
Computed signals for paginatedLogs, totalPages, navigation state
Auto-reset to first page when filters change
Conditional display (only shows when multiple pages exist)

3. Enhanced UI/UX

Search across message, context, and data fields
Filter by log level (Info, Warning, Error)
Individual delete buttons with confirmation dialogs
"Clear All" button with confirmation
Material Icons integration throughout

4. Type Safety & Documentation

Fixed data?: any → data?: unknown for proper type checking
Corrected copy-paste documentation errors
Added comprehensive JSDoc comments

5. Test Coverage

Created 25 component tests (filtering, pagination, CRUD)
Total: 72 tests passing (up from 47)
Coverage: filtering, pagination, expansion, delete/clear operations

6. DDD Compliance

✅ Layer separation maintained
✅ Signal-based reactive state
✅ Unidirectional data flow
✅ Single source of truth preserved

Task Domain Production Patterns

The task domain implements 10 production-grade patterns:

1. Robust Error Handling

Try/catch blocks around all localStorage operations prevent silent failures. Handles quota exceeded, corrupted data, and access failures gracefully.

2. Full Type Safety

Zero any casts throughout the codebase. All types properly defined and leveraged for compile-time safety.

3. Correct Object Comparison

Custom deepEquals() utility replaces unreliable JSON.stringify() for proper change detection with Date objects and arrays.

4. Efficient Data Derivation

Computed signals ensure derived state (filters, counts, metrics) only recalculates when dependencies change.

5. Consistent State Paradigm

Pure signal-based unidirectional data flow. Removed all [(ngModel)] in favor of explicit [value]/(input) bindings.

6. Clean Code

Zero console.log statements in production code. Development artifacts removed.

7. Enforce Immutability

All state operations create new objects/arrays. No mutations anywhere (.map(), .filter(), spread operators).

8. Isolate History Logic (SRP)

Dedicated TaskHistoryService handles all history operations. TaskService acts as a focused orchestrator.

9. Centralize Constants

task.constants.ts eliminates magic strings. All configuration values centralized for maintainability.

10. Dumb Presentation Layer

Components delegate business logic to services. Pure presentation logic only (rendering, event delegation).

🚀 Key Features

1. Task Management

Create, read, update, delete tasks
Status tracking (Pending → In Progress → Completed)
Priority levels (Low, Medium, High)
Multi-tag support (Bug, Risk, Feature)
Delta-based updates (only log changed fields)

2. Audit History

Every change is tracked:

history: [{
  modifiedAt: Date,
  changes: {
    status: { oldValue: 'pending', newValue: 'in-progress' }
  }
}]

3. System Logging

Production-ready logging with convenience API:

// Clean logging with convenience methods
this.loggingService.logInfo('Task updated', {
  context: 'TaskService.update',
  data: { taskId: 123, updates: { status: 'completed' } }
});

this.loggingService.logWarn('Account balance low', {
  context: 'BalanceService.check',
  data: { accountId: 456, balance: 100 }
});

this.loggingService.logError('Validation failed', {
  context: 'AccountService.add',
  data: { errors: ['Name required'] }
})

Info logs: Task creation, updates
Warning logs: Soft/hard deletes
Error logs: Operations on non-existent tasks
Features: Pagination (5/page), search, level filtering, delete/clear, expandable data
Auto-sorted: Newest first with timezone-aware timestamps

4. Multiple Domains & Views

Task Domain:

List View: Filterable task list with full history
Kanban Board: Drag-and-drop columns with sorting
Metrics Dashboard: Real-time computed statistics

Logging Domain:

System Logs: Paginated activity log with search, filtering, delete/clear

Balance Sheet Domain:

Account Management: Track assets and liabilities
Balance Recording: Historical balance entries
Net Worth Dashboard: Real-time financial calculations

Workflow Engine:

Instance Tracker: Monitor active workflows
Template Library: Reusable workflow definitions

5. Reactive State

// Single source of truth
private _tasks = signal<Task[]>([])

// Computed derived state
readonly completionRate = computed(() => {
  const total = this._tasks().length
  const completed = this.completedTaskCount()
  return ((completed / total) * 100).toFixed(1) + '%'
})

// Auto-sorted logs (newest first)
readonly logs = computed(() => {
  return [...this._logs()].sort((a, b) =>
    b.timeStamp.getTime() - a.timeStamp.getTime()
  )
})

📖 Code Examples

Creating a Task

this.taskService.add({
  title: 'Fix login bug',
  content: 'Users cannot login with special characters',
  status: TaskStatus.Pending,
  priority: TaskPriority.High,
  tags: [TaskTags.Bug]
})

Computed Signal Usage

export class TaskComponent {
  // Reference the signal (don't call it)
  taskCount = this.taskState.taskCount

  // Template automatically unwraps with ()
  // <span>{{ taskCount() }}</span>
}

Drag & Drop Status Update

drop(event: CdkDragDrop<any>, newStatus: TaskStatus) {
  const task = event.item.data
  if (task.status !== newStatus) {
    this.taskService.update(task.id, { status: newStatus })
  }
}

Immutable State Updates

// ❌ BAD: Mutates existing array
toggleTag(tag: TaskTags) {
  this.tags.push(tag)  // Mutation!
}

// ✅ GOOD: Creates new array
toggleTag(tag: TaskTags) {
  const currentTags = this.newTags()
  this.newTags.set([...currentTags, tag])  // Immutable
}

Error Handling Pattern

saveAll(tasks: Task[]): boolean {
  try {
    const tasksCopy = tasks.map(task => ({ ...task }))
    localStorage.setItem(TASK_STORAGE_KEY, JSON.stringify(tasksCopy))
    return true
  } catch (error) {
    if (error.name === 'QuotaExceededError') {
      console.error('Storage quota exceeded')
    }
    return false  // Graceful degradation
  }
}

🎓 Learning Path

Beginner

Study task.model.ts - domain modeling with TypeScript
Review task.constants.ts - centralized configuration pattern
Read task.repository.ts - repository pattern with error handling
Explore task.service.ts - CRUD orchestration

Intermediate

Analyze taskState.service.ts - signals + business logic
Study taskHistory.service.ts - Single Responsibility Principle
Review object-comparison.util.ts - proper deep equality
Examine task-add.component.ts - signal-based forms
Study task-list.component.ts - filtering & computed signals

Advanced

Examine task-kanban.component.ts - CDK drag-drop + dumb components
Understand immutability patterns throughout
Study history tracking implementation
Analyze revert/undo functionality
Review error handling strategies

🛠️ Technical Stack

Angular 18+ (standalone components)
TypeScript 5.0+
Angular CDK (drag-drop)
Signals API (reactive state)
localStorage (persistence)

📦 Project Structure

notes-app/
├── src/app/
│   ├── domains/
│   │   ├── task/           # Task domain (complete with history)
│   │   ├── logging/        # Logging domain (complete with pagination)
│   │   ├── balance-sheet/  # Balance sheet domain (complete)
│   │   ├── workflow/       # Workflow engine domain (complete)
│   │   └── notes/          # Notes domain (planned)
│   ├── shared/
│   │   └── utils/          # Date formatting, serialization, comparison
│   └── layout/             # Header, sidebar, footer
└── README.md

🔄 Data Flow

User Action (Component)
    ↓
TaskService (Business Logic)
    ↓
TaskRepository (Persistence)
    ↓
TaskStateService (State Update)
    ↓
Computed Signals Update
    ↓
Components Auto-Render

Unidirectional flow ensures predictable state updates.

🎯 Design Patterns Used

Pattern	Location	Purpose
Repository	`task.repository.ts`, `logging.repository.ts`	Abstract storage with error handling
Service Layer	`task.service.ts`, `logging.service.ts`	CRUD orchestration
State Management	`taskState.service.ts`, `loggingState.service.ts`	Centralized reactive state + business logic
Single Responsibility	`taskHistory.service.ts`	Dedicated history management
Container/Presenter	Task components	Separation of concerns (dumb UI)
Computed Properties	Signals	Efficient derived state (sorting, filtering)
Immutability	All layers	Spread operators, no mutations
Constants Pattern	`task.constants.ts`	No magic strings
Deep Equality	`object-comparison.util.ts`	Proper change detection
Unidirectional Data Flow	Components	Explicit bindings, no `[(ngModel)]`
Audit Log	History tracking + system logs	Compliance & debugging
Soft Delete	`deleted` flag	Data recovery
Error Boundary	Repository layer	Graceful localStorage failures
Cross-Domain Integration	Task → Logging	Loose coupling via service injection
Delta Tracking	`task-add.component.ts`	Only log actual changes

📝 Key Learnings

Why Signals Over RxJS?

✅ Simpler mental model (no subscriptions)
✅ Automatic cleanup
✅ Fine-grained reactivity
✅ Better performance

Why 3 Layers?

✅ Easy to test (mock each layer)
✅ Swap implementations (localStorage → HTTP)
✅ Clear responsibilities
✅ Scalable architecture

Why Immutability?

✅ Predictable state changes
✅ Easier debugging (state never mutates unexpectedly)
✅ Enables time-travel debugging
✅ Prevents unintended side effects
✅ Better performance with change detection

Why Single Responsibility?

✅ Services stay focused (TaskHistoryService vs TaskService)
✅ Easier to test in isolation
✅ Simpler to reason about
✅ More maintainable over time

Why Domain Structure?

✅ All task code in one place
✅ Easy to find related files
✅ Could extract to library
✅ Team can own entire domain

🚧 Future Enhancements

💻 Development

Development server

Run ng serve for a dev server. Navigate to http://localhost:4200/.

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory.

📚 Resources

🤝 Contributing

This is a learning repository. Feel free to:

Fork and experiment
Open issues with questions
Submit PRs with improvements
Use as a reference for your projects

📄 License

MIT License - Feel free to use this code for learning and reference.

🎓 Author

Daniel Hoffman (@dan7hoffman)

Built as an iterative learning exercise to master Angular patterns and clean architecture.

🔖 Tags

angular typescript signals clean-architecture crud drag-drop state-management domain-driven-design immutability single-responsibility error-handling type-safety unidirectional-data-flow logging audit-trail delta-tracking learning reference best-practices production-ready

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.vscode		.vscode
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
README.md		README.md
angular.json		angular.json
codebase.md		codebase.md
package-lock.json		package-lock.json
package.json		package.json
server.ts		server.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json

dan7hoffman/notes-app

Folders and files

Latest commit

History

Repository files navigation