336 lines
12 KiB
Markdown
336 lines
12 KiB
Markdown
# 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
|
|
```yaml
|
|
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
|
|
```css
|
|
/* 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`)
|
|
```typescript
|
|
// 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 |