forensic-pathways/context.md

ForensicPathways Architecture System Prompt

Project Overview

ForensicPathways is a curated directory of Digital Forensics and Incident Response (DFIR) tools, methods, and concepts built with Astro and TypeScript. It serves as an educational and professional resource for forensic investigators, following the NIST SP 800-86 framework (Kent, Chevalier, Grance & Dang).

Core Technology Stack

• Framework: Astro (static site generator with islands architecture)
• Language: TypeScript with strict typing
• Styling: Vanilla CSS with custom properties (CSS variables)
• Data Storage: YAML files for tool catalog
• Content: Astro Content Collections for knowledge base articles
• Authentication: OIDC (OpenID Connect) with configurable requirements
• AI Integration: Mistral API for workflow recommendations
• File Storage: Nextcloud with local fallback
• Version Control: Git integration for community contributions

Data Model Architecture

Core Entity: Tool

name: string           # Tool identifier
icon: string?          # Emoji icon
type: 'software'|'method'|'concept'  # Tool classification
description: string    # Detailed description
domains: string[]      # Forensic domains (incident-response, malware-analysis, etc.)
phases: string[]       # NIST framework phases (data-collection, examination, analysis, reporting)
platforms: string[]   # Operating systems (for software only)
skillLevel: string     # novice|beginner|intermediate|advanced|expert
url: string           # Primary documentation/homepage
projectUrl: string?   # Hosted instance URL (CC24 server)
license: string?      # Software license
knowledgebase: boolean? # Has detailed documentation
tags: string[]        # Searchable keywords
related_concepts: string[]? # Links to concept-type tools

Taxonomies

• Domains: Forensic specializations (7 main domains)
• Phases: NIST investigation phases (4 phases)
• Domain-Agnostic-Software: Cross-cutting tools and platforms
• Skill Levels: Standardized competency requirements

Component Architecture

Layout System

• BaseLayout.astro: Global layout with theme system, authentication setup, shared utilities
• Navigation.astro: Main navigation with active state management
• Footer.astro: Site footer with links and licensing info

Core Components

• ToolCard.astro: Individual tool display with metadata, actions, and type-specific styling
• ToolMatrix.astro: Matrix view showing tools by domain/phase intersection
• ToolFilters.astro: Search, filtering, and view controls
• AIQueryInterface.astro: AI-powered workflow recommendation system

Utility Components

• ShareButton.astro: URL sharing with multiple view options
• ContributionButton.astro: Authenticated contribution links
• ThemeToggle.astro: Light/dark/auto theme switching

Feature Systems

1. Authentication System (src/utils/auth.ts)

• OIDC Integration: Uses environment-configured provider
• Contextual Requirements: Different auth requirements for contributions vs AI features
• Session Management: JWT-based with configurable expiration
• Client-Side Utilities: Window-level auth checking functions

2. AI Recommendation System

• Dual Modes:
  • Workflow mode: Multi-phase recommendations for scenarios
  • Tool mode: Specific tool recommendations for problems
• Rate Limiting: Queue-based system with status updates
• Data Integration: Uses compressed tool database for AI context
• Response Validation: Ensures AI only recommends existing tools

3. Contribution System

• Git Integration: Automated issue creation via Gitea/GitHub/GitLab APIs
• Tool Contributions: Form-based tool submissions
• Knowledge Base: Rich text with file upload support
• Validation: Client and server-side validation with Zod schemas

4. File Upload System

• Primary: Nextcloud integration with public link generation
• Fallback: Local file storage with public URL generation
• Validation: File type and size restrictions
• Rate Limiting: Per-user upload quotas

Styling Architecture

CSS Custom Properties System

/* Core color system */
--color-primary: /* Adaptive based on theme */
--color-accent: /* Secondary brand color */
--color-bg: /* Main background */
--color-text: /* Primary text */

/* Component-specific colors */
--color-hosted: /* CC24 server hosted tools */
--color-oss: /* Open source tools */
--color-method: /* Methodology entries */
--color-concept: /* Knowledge concepts */

/* Theme system */
[data-theme="light"] { /* Light theme values */ }
[data-theme="dark"] { /* Dark theme values */ }

Component Styling Patterns

• Card System: Consistent .card base with type-specific variants
• Badge System: Status and metadata indicators
• Button System: Semantic button classes with size variants
• Grid System: CSS Grid with responsive breakpoints

Data Flow Architecture

1. Data Loading (src/utils/dataService.ts)

// Daily randomization with seeded shuffle
getToolsData() → shuffled tools array
getCompressedToolsDataForAI() → AI-optimized dataset
clearCache() → cache invalidation

2. Client-Side State Management

• Global Tools Data: Attached to window.toolsData
• Filter State: Component-local state with event emission
• View State: Grid/Matrix/AI view switching
• Modal State: Tool detail overlays with multi-modal support

3. Search and Filtering

• Text Search: Name, description, tags
• Faceted Filtering: Domain, phase, skill level, license type
• Tag Cloud: Frequency-weighted tag selection
• Real-time Updates: Immediate filtering with event system

API Architecture

Endpoint Structure

/api/auth/         # Authentication endpoints
  login.ts         # OIDC initiation
  process.ts       # OIDC callback processing
  status.ts        # Auth status checking

/api/contribute/   # Contribution endpoints
  tool.ts          # Tool submissions
  knowledgebase.ts # KB article submissions

/api/ai/          # AI features
  query.ts         # Workflow recommendations
  queue-status.ts  # Queue monitoring

/api/upload/      # File handling
  media.ts         # File upload processing

/api/health.ts    # System health check

Response Patterns

All APIs use consolidated response utilities (src/utils/api.ts):

• Success: apiResponse.success(), apiResponse.created()
• Errors: apiError.badRequest(), apiError.unauthorized(), etc.
• Server Errors: apiServerError.internal(), etc.

File Organization Patterns

Page Structure

• Static Pages: About, impressum, status
• Dynamic Pages: Tool details, knowledge base articles
• Authenticated Pages: Contribution forms
• API Routes: RESTful endpoints with consistent naming

Utility Organization

• Tool Operations: toolHelpers.ts - Core tool manipulation
• Data Management: dataService.ts - YAML loading and caching
• Authentication: auth.ts - OIDC flow and session management
• External APIs: gitContributions.ts, nextcloud.ts
• Rate Limiting: rateLimitedQueue.ts - AI request queuing

Key Architectural Decisions

1. Static-First with Dynamic Islands

• Astro's islands architecture for interactivity
• Static generation for performance
• Selective hydration for complex components

2. YAML-Based Data Management

• Human-readable tool catalog
• Git-friendly versioning
• Type-safe loading with Zod validation

3. Contextual Authentication

• Optional authentication based on feature
• Graceful degradation for unauthenticated users
• Environment-configurable requirements

4. Multi-Modal UI Patterns

• Grid view for browsing
• Matrix view for relationship visualization
• AI interface for guided recommendations

5. Progressive Enhancement

• Core functionality works without JavaScript
• Enhanced features require client-side hydration
• Responsive design with mobile-first approach

Development Patterns

Component Design

• Props interfaces with TypeScript
• Consistent styling via CSS classes
• Event-driven communication between components
• Server-side rendering with client-side enhancement

Error Handling

• Comprehensive try-catch in API routes
• User-friendly error messages
• Graceful fallbacks for external services
• Logging for debugging and monitoring

Performance Optimizations

• Daily data randomization with caching
• Compressed datasets for AI context
• Rate limiting for external API calls
• Efficient DOM updates with targeted selectors

This architecture emphasizes maintainability, user experience, and extensibility while managing the complexity of a multi-feature forensics tool directory.

Absolutely Essential (Core Architecture - 8 files)

File: src/data/tools.yaml.example Why: Defines the core data model - what a "tool" is, the schema, domains, phases, etc. Without this, an AI can't understand what the application manages.

File: src/pages/index.astro Why: Main application entry point showing the core functionality (filters, matrix, AI interface, tool grid). Contains the primary application logic flow.

File: src/layouts/BaseLayout.astro Why: Global layout with theme system, authentication setup, and shared utility functions. Shows the overall app structure.

File: src/utils/dataService.ts Why: Core data loading and processing logic. Essential for understanding how data flows through the application.

File: src/utils/toolHelpers.ts Why: Core utility functions used throughout the app (slug creation, tool identification, hosting checks).

File: src/styles/global.css Why: Complete styling system - defines visual architecture, component styling, theme system, responsive design.

File: src/env.d.ts Why: Global TypeScript definitions and window interface extensions. Shows the global API surface.

File: src/components/ToolCard.astro Why: Shows how the core entity (tools) are rendered and structured. Represents the component architecture pattern.

Secondary Priority (Major Features - 4 files)

File: src/components/ToolMatrix.astro - Matrix view functionality File: src/components/AIQueryInterface.astro - AI recommendation system
File: src/utils/auth.ts - Authentication system File: src/content/config.ts - Content collection schema

Strategy for Context Management

1. Always provide: The 8 essential files above
2. Add selectively: Include 1-3 secondary files based on the specific development task
3. Reference others: Mention other relevant files by name/purpose without including full content

user01@altiera /v/h/u/P/cc24-hub (main)> tree src src ├── components │ ├── AIQueryInterface.astro │ ├── ContributionButton.astro │ ├── Footer.astro │ ├── Navigation.astro │ ├── ShareButton.astro │ ├── ThemeToggle.astro │ ├── ToolCard.astro │ ├── ToolFilters.astro │ └── ToolMatrix.astro ├── content │ ├── config.ts │ └── knowledgebase │ ├── android-logical-imaging.md │ ├── kali-linux.md │ ├── misp.md │ ├── nextcloud.md │ ├── regular-expressions-regex.md │ └── velociraptor.md ├── data │ ├── tools.yaml │ └── tools.yaml.example ├── env.d.ts ├── layouts │ └── BaseLayout.astro ├── pages │ ├── about.astro │ ├── api │ │ ├── ai │ │ │ ├── query.ts │ │ │ └── queue-status.ts │ │ ├── auth │ │ │ ├── login.ts │ │ │ ├── process.ts │ │ │ └── status.ts │ │ ├── contribute │ │ │ ├── knowledgebase.ts │ │ │ └── tool.ts │ │ ├── health.ts │ │ └── upload │ │ └── media.ts │ ├── auth │ │ └── callback.astro │ ├── contribute │ │ ├── index.astro │ │ ├── knowledgebase.astro │ │ └── tool.astro │ ├── impressum.astro │ ├── index.astro │ ├── knowledgebase │ │ └── [slug].astro │ ├── knowledgebase.astro │ └── status.astro ├── styles │ └── global.css └── utils ├── api.ts ├── auth.ts ├── dataService.ts ├── gitContributions.ts ├── nextcloud.ts ├── rateLimitedQueue.ts └── toolHelpers.ts 17 directories, 47 files