CLAUDE MAX

Documentation for Developers

CLAUDE-MAX - Full Documentation

DEPRECATED (Session 135): All essential rules have been consolidated into CLAUDE.md. This file is archived for historical reference. DO NOT read this file for current rules. Use CLAUDE.md + MCP get_conventions() instead.

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. START HERE - Read this files below in the order they are listed, before starting any task (If you already read any of these files before during this session, skip this step and continue with the analysis of the data in this file):

AGENTS.md
AGENTS-AI-Instructions
CLAUDE.md
Claude-Docs (all docs inside)
AI Agent Task System - CRITICAL: Self-learning AI system
Then continue with the analysis of the data in this file:

🤖 AI Agent Task System (Self-Learning)

IMPORTANT: GoGrab Space has a sophisticated AI Agent Task System that tracks your work for continuous improvement. When working on significant tasks:

Decision Logging Protocol

For every non-trivial decision, mentally note:

Question: What decision was being made?
Options: What alternatives were considered?
Chosen: What was selected?
Reasoning: Why? (MOST IMPORTANT - this trains future AI!)
Confidence: 0-1 score

When to Log Decisions

Log	Don't Log
Library/framework choice	Fixing typos
Architecture decisions	Simple renames
Implementation approach	Obvious patterns
Error recovery strategy	Standard imports
State management choice	Basic CRUD

Backend API (for programmatic logging)

// Create Task
POST /api/ai-agents/tasks
{ type: 'vibe-coding', goal: 'User request summary' }

// Log Decision
POST /api/ai-agents/tasks/:taskId/sessions/:sessionId/decisions
{
  type: 'implementation-choice',
  question: 'Which approach for X?',
  options: ['A', 'B', 'C'],
  chosen: 'B',
  reasoning: 'Why B is best...',
  confidence: 0.85
}

Full Documentation: See AGENT-TASK-SYSTEM.md

Development Commands

Provide a Chain-Of-Thought analysis before answering.
Review the project files thoroughly. If there is anything you need referenced that's missing, ask for it.
If you're unsure about any aspect of the task, ask for clarification. Don't guess. Don't make assumptions.
Don't do anything unless explicitly instructed to do so. Nothing "extra".
Always preserve everything from the original files, except for what is being updated.
Write code in artifacts in full with no placeholders. If you get cut off, I'll say "continue"

TDD Workflow

When implementing new features, follow this Test-Driven Development workflow:

Write tests - Create comprehensive tests for the feature first (TDD approach)
Commit tests - Commit the test suite before implementation
Code implementation - Write the minimum code to pass the tests
Iterate - Refactor and improve until all tests pass and code quality standards are met
Commit implementation - Commit the working implementation

This ensures:

Clear specification before coding
Testable design from the start
Incremental progress with validation
Clean git history separating tests from implementation

Build & Development

# Serve main application
npx nx serve gograb-space

# Build for production
npx nx build gograb-space

# Build all libraries
npx nx run-many -t build

# Run tests
npx nx test <project-name>
npx nx run-many -t test

# Lint code
npx nx lint <project-name>
npx nx run-many -t lint

# Show project details
npx nx show project <project-name>

# Visualize project graph
npx nx graph

Library Management

For the monorepo "editor" - skip this section and prioritize the analysis of the data in this file: LIBRARY MANAGEMENT

# Generate new Angular library
npx nx g @nx/angular:lib <lib-name> --directory=libs/core

# Generate new Angular component
npx nx g @nx/angular:component <component-name> --project=<project-name>

# Generate new service
npx nx g @nx/angular:service <service-name> --project=<project-name>

Architecture Overview

GoGrab Space is a modular Angular 20 monorepo built with Nx, designed as a multi-tenant platform with dynamic module loading and event-driven architecture.

Key Technologies

Framework: Angular 20.x
Build System: Angular CLI with @angular/build
Monorepo Tool: Nx Workspace 21.x
Package Manager: Yarn
Testing: Vitest for unit tests, Playwright for E2E tests
Language: TypeScript 5.8
Styling: SCSS
State Management: Signals (primary), RxJS (async), NGXS (high-level only)

Core Principles

SOLID principles applied strictly
DRY (Don't Repeat Yourself) - maximum code reuse
Event-driven architecture for loose coupling
Multi-tenant isolation with tenant-aware components
Standalone components only (no NgModules)
OnPush change detection strategy
State Management Hierarchy: Signals (preferred) → RxJS (async) → NGXS (high-level only)
Always use RxJS, never use Promises for async operations
Never use setTimeout except in tests - use RxJS timer/delay instead

NX Monorepo Structure

This is an Nx monorepo workspace
Follow Nx conventions for library and app organization
Use Nx generators when creating new libraries or components
Respect the established folder structure: libs/ for shared libraries, apps/ for applications
Update tsconfig.base.json path mappings when creating new libraries
Use Nx tags for proper dependency management
Follow Nx naming conventions for projects and libraries

Development Rules

Development phase: No backward compatibility needed
No timeouts (forbidden)
Apply SOLID principles (mandatory)
Follow DRY principle
Clean, robust, maintainable code
Update barrel exports when necessary
Validate component/files existence before use
Use existing utilities and services (analyze code when needed)
Use one file per class, service or component
Use context7 when is possible

Project Structure

apps/gograb-space/          # Main Angular application
libs/core/                  # Core system libraries
  ├── utilities/            # Cross-cutting utilities (@gograb-space/utilities)
  ├── log-system/          # Logging system (@libs-core/log-system)
  ├── event-system/        # Event bus (@libs-core/event-system)
  ├── module-base/         # Module contracts (@libs-core/module-base)
  ├── ui-framework/        # Design system (@libs-core/ui-framework)
  └── security/            # Auth & authorization (@libs-core/security)

Core Libraries

@gograb-space/utilities - Foundation utilities ✅ Completado

DateUtils, StringUtils, ValidationUtils, ObjectUtils, ArrayUtils
All utilities are pure functions with comprehensive testing
Browser-compatible, no Node.js dependencies

@libs-core/log-system - Comprehensive logging ✅ Completado (MVP)

Multi-level logging (trace, debug, info, warn, error, critical)
ConsoleAppender (SSR-safe)
JsonFormatter with sensitive data redaction
Decorators: @loggable, @logError, @performance
Multi-tenant aware with correlation IDs
Logger child with specific context
Sampling for log volume reduction

@libs-core/event-system - Event-driven communication ✅ Completado

Domain Events and System Events (typed)
Event sourcing capabilities for debugging
Multi-tenant event isolation
Performance monitoring of events
Full integration with Log System

@libs-core/security - Security infrastructure ✅ Completado

JWT authentication with auto-refresh
RBAC (Role-Based Access Control) granular
Standalone guards: authGuard, roleGuard, permissionGuard
Interceptors: AuthInterceptor, ContextInterceptor (auto tenant injection)
XSS/CSRF protection, SecureStorageService
Multi-tenant context selection
Full integration with @libs-core/shared-models

@libs-core/module-base - Module contracts ✅ Completado

Standardized contracts: BrowserModuleContract, ModuleManifest
Auto-registration via @ModuleDecorator
ModuleRegistryService, ModuleDiscoveryService
ModuleStateService (Signal-based)
ModuleConfigurationService (multi-tenant)
Base components: BaseModuleComponent, ModuleLayoutComponent
Full integration with Event System and Log System

@libs-core/module-integrator - Module orchestration ✅ Completado

Dynamic module integration with runtime discovery
Dependency resolution with circular dependency detection
Configuration management with intelligent caching (5-min TTL)
Lifecycle management for all module states
Multi-tenant support with isolated configurations
Contract and dependency validation before activation
Performance optimized with Signals and OnPush

@libs-core/shared-models - Shared models ✅ Completado

Tenant: Context, Config, Features, ContextInfo
Authentication: UserProfile, AuthState, LoginResult, SelectionResult
RBAC: Role, Permission (with free actions)
UI: UiConfig, BrandingConfig, ThemeConfig, UserPreferences
API: ApiResponse, PaginationRequest, PaginationResponse, ErrorResponse
Common: BaseEntity, AuditFields, DateRange, KeyValue
Strict TypeScript, tree-shaking friendly, JSDoc documented

@libs-core/mock-api - API mocking system ✅ Completado

HTTP interceptor with provideHttpClient and withInterceptors
Type-safe route system (dynamic params, wildcards, query params)
Full RxJS support (Observables, Promises, sync values)
Optional persistence: IndexedDB, LocalStorage, Memory (TTL, auto-cleanup)
Middleware system (pre/post processing)
DataGenerator for realistic mock data
Utilities: RouteMatcher, MockValidator, MiddlewareFactory
Intelligent Storage integration

@libs-core/action-registry - Command pattern ✅ Completado

Centralized registry for module public actions
Standardized handler for action execution
Execution context with typed results
Integration with Security and Event System

@libs-core/data-access - Data access layer ✅ Completado

Repositories and API services
State management with NGXS
Integrated CacheService
Data events and synchronization
Domain facades, queries, result mappers

@libs-core/data-binding - Data binding system ✅ Completado (MVP)

Declarative parameter value resolution from multiple sources
Manual, Repository, and Config resolvers (Event/Action/Transform prepared for Singularity)
Type-safe binding configuration with discriminated union types
Observable-based API with RxJS
Intelligent caching with TTL configuration
Resolution statistics (success/failure, cache hits/misses)
Integration with ParameterMetadata from shared-models
Full integration with ContextService (multi-tenant)
96 comprehensive unit tests, 2 functional example components

@libs-core/ui-framework - Design system ✅ Completado

Base components: Buttons, Cards, Forms, Modals, Dialogs, Tooltips
Layout components: Header, Sidebar, Footer, Grid, NavBar
Design tokens: Colors, typography
Dynamic theme system
Centralized iconography
Common directives: ClickOutside, Autofocus

@gograb-space/user-management - User management module ✅ Completado

Complete multi-tenant user management
Administration UI
Integration with Security and RBAC
Full CRUD operations
Role and permission assignment

Development Standards

Code Generation Principles

CORE DIRECTIVE: Generate ONLY what is requested. No extra code, no placeholders, no TODOs.

ANGULAR ONLY: Generate exclusively Angular code. This project and all libraries run in the browser.

Minimal & Necessary Code

Write only the code that will be used
No boilerplate unless specifically required
No defensive programming unless explicitly requested
No future-proofing unless specified
Never suppose datatypes, always use defined types

Angular 20 Features

Use standalone components exclusively (standalone: true)
Implement OnPush change detection strategy
Prefer Signals over Observables for reactive state
Use new control flow syntax (@if, @for, @switch)
ALWAYS use inject() function instead of constructor parameter injection for dependency injection
- ESLint rule: @angular-eslint/prefer-inject
- Constructor parameters should only be used for configuration values, not injected services
- Use ng generate @angular/core:inject to automatically migrate constructor injection to inject()
Prefer Input<T> over @Input when possible
Prefer Output<T> over @Output when possible
No deprecated APIs or components

State Management Hierarchy

This project follows a strict hierarchy for state management based on scope and complexity:

1. Signals (Preferred - Default Choice) 🎯

Use for:

Local component state
Simple reactive values
Derived/computed values
Component-level effects

Examples:

// ✅ Component state
export class CounterComponent {
  count = signal(0);
  doubled = computed(() => this.count() * 2);

  increment() {
    this.count.update(v => v + 1);
  }

  // Effects for side effects
  constructor() {
    effect(() => {
      console.log('Count changed:', this.count());
    });
  }
}

// ✅ Service state
export class UserPreferencesService {
  private themeSignal = signal<'light' | 'dark'>('light');
  theme = this.themeSignal.asReadonly();

  setTheme(theme: 'light' | 'dark') {
    this.themeSignal.set(theme);
  }
}

2. RxJS (Asynchronous Operations)

Use for:

HTTP requests and API calls
Event streams and user interactions
Time-based operations (debounce, throttle, interval)
Complex async workflows with operators
WebSocket connections
Real-time data streams

Examples:

// ✅ HTTP operations
export class DataService {
  private http = inject(HttpClient);

  getData(): Observable<Data> {
    return this.http.get<Data>('/api/data').pipe(
      retry(2),
      timeout(5000),
      catchError(this.handleError)
    );
  }

  // ✅ Complex async workflows
  searchWithDebounce(searchTerm$: Observable<string>): Observable<Result[]> {
    return searchTerm$.pipe(
      debounceTime(300),
      distinctUntilChanged(),
      switchMap(term => this.search(term)),
      catchError(() => of([]))
    );
  }
}

// ✅ Event streams
export class FormComponent {
  private destroyRef = inject(DestroyRef);

  ngOnInit() {
    fromEvent(this.input.nativeElement, 'input')
      .pipe(
        debounceTime(300),
        map((event: Event) => (event.target as HTMLInputElement).value),
        takeUntilDestroyed(this.destroyRef)
      )
      .subscribe(value => this.handleInput(value));
  }
}

3. NGXS (High-Level Components Only)

Use ONLY for:

Global application state (shared across multiple modules)
High-level module state (main app components, feature modules)
Cross-cutting concerns (authentication, tenant context)
State that needs to be shared across unrelated components

DO NOT use for:

Local component state
Service-level caching
UI state (modals, tabs, accordions)
Form state

Examples:

// ✅ Global auth state (HIGH-LEVEL)
@State<AuthStateModel>({
  name: 'auth',
  defaults: {
    user: null,
    token: null,
    isAuthenticated: false
  }
})
export class AuthState {
  @Action(Login)
  login(ctx: StateContext<AuthStateModel>, action: Login) {
    return this.authService.login(action.credentials).pipe(
      tap(result => {
        ctx.patchState({
          user: result.user,
          token: result.token,
          isAuthenticated: true
        });
      })
    );
  }
}

// ✅ Application-level tenant context (HIGH-LEVEL)
@State<TenantStateModel>({
  name: 'tenant',
  defaults: { currentTenant: null }
})
export class TenantState { ... }

// ❌ WRONG - Don't use NGXS for component state
@Select(UserState.firstName) firstName$!: Observable<string>; // Use Signal instead

Anti-Patterns to Avoid

// ❌ NO Promises - Always use RxJS
async getData() {
  const data = await fetch('/api/data');
  return data.json();
}

// ✅ YES - RxJS Observable
getData(): Observable<Data> {
  return this.http.get<Data>('/api/data');
}

// ❌ NO NGXS for local state
export class UserCardComponent {
  @Select(UserState.firstName) firstName$!: Observable<string>;
}

// ✅ YES - Signal for local state
export class UserCardComponent {
  firstName = input.required<string>();
  // or if managing locally:
  firstName = signal('');
}

// ❌ NO Signals for async operations
userClick = signal(null); // Then manually handling async

// ✅ YES - RxJS for async
userClick$ = fromEvent(button, 'click').pipe(
  switchMap(() => this.loadData())
);

// ❌ NO setTimeout
setTimeout(() => this.doSomething(), 1000);

// ✅ YES - RxJS timer (in production code)
timer(1000).pipe(
  takeUntilDestroyed(this.destroyRef)
).subscribe(() => this.doSomething());

// ⚠️ EXCEPTION - setTimeout ONLY in tests
it('should handle delay', (done) => {
  setTimeout(() => {
    expect(component.value).toBe(expected);
    done();
  }, 100);
});

Decision Tree

Need reactive state?
├─ Local to component/service?
│  └─ Use Signal ✅
├─ Async operation (HTTP, events, time-based)?
│  └─ Use RxJS ✅
├─ Global/cross-module state?
│  ├─ High-level (app/module)?
│  │  └─ Use NGXS ✅
│  └─ Low-level (component)?
│     └─ Use Signal + Injectable Service ✅
└─ Simple derived value?
   └─ Use computed() Signal ✅

Code Quality

Never use any type - use SafeAny if absolutely necessary
Avoid allowSignalWrites and queueMicrotask
Use RxJS over Promises for async operations
Apply strict TypeScript configuration
Follow kebab-case for file naming
BROWSER ONLY: All code must be compatible with browser environments

Testing Requirements

Tests only when explicitly requested or required
Location: tests folder at library/app root
- Example: /libs/core/utilities/tests/, on root of library
Group related test suites logically
Naming convention: [feature-name].test.ts
Test only the functionality that exists
No test stubs or placeholder tests
Focus on business logic and critical paths
Use descriptive test names that explain behavior
Mock external dependencies appropriately
Minimum 90% test coverage
Arrange-Act-Assert pattern for unit tests
Integration tests for module contracts
E2E tests for critical user flows

Multi-Tenant Considerations

All services must be tenant-aware
Event isolation by tenant context
Logging with tenant correlation IDs
Security policies per tenant

Barrel Exports

Always update barrel exports in src/index.ts when adding new modules:

// Add to appropriate index.ts
export * from './lib/new-feature/new-feature';

Library Dependencies

Core libraries have the following dependency hierarchy:

utilities - no dependencies (foundation)
shared-models - no dependencies (pure models)
log-system - depends on utilities
event-system - depends on utilities, log-system
security - depends on utilities, log-system, shared-models
module-base - depends on utilities, log-system, event-system, security
module-integrator - depends on module-base, security, log-system, event-system, utilities
action-registry - depends on security, log-system, event-system, utilities
data-access - depends on security, log-system, event-system, mock-api, utilities
data-binding - depends on utilities, log-system, shared-models, security (ContextService)
mock-api - depends on utilities, log-system
ui-framework - depends on log-system, event-system (minimal)
user-management - depends on security, ui-framework, data-access, shared-models, log-system, event-system

Development Phase Notes

Currently in development phase - no backward compatibility constraints
Focus on clean, robust, maintainable code
Validate component/file existence before use
Leverage existing utilities and services

Workspace Configuration

Package Manager: Yarn
Build System: Nx 21.4.1
Testing: Vitest with Angular integration
E2E: Playwright
Linting: ESLint with Angular rules

When developing, always check existing implementations in similar modules before creating new functionality to maintain consistency and reuse existing patterns.

📚 Technical Documentation References

This section provides comprehensive references to technical documentation for AI code generators. These references are optional but highly recommended for informed decision-making during development, refactoring, or architectural changes.

📖 How to Use This Documentation

For AI Code Generators (like Claude Code):

Consult relevant documentation before implementing new features or modifications
Prioritize README.md for overview, then requirements.md and design.md for detailed specifications
Use tasks.md to understand implementation roadmap and current status
Review ADRs (Architecture Decision Records) for context on architectural choices

Documentation Priority:

📖 README.md - High-level overview and quick reference
📋 requirements.md - Functional and non-functional requirements
🎨 design.md - Architectural decisions and technical design
✅ tasks.md - Implementation tasks and progress tracking