# packetwarden/wetnav architecture

> Architecture diagram of the GitHub repository packetwarden/wetnav, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/packetwarden/wetnav
- Repository: https://github.com/packetwarden/wetnav

## Overview

##### Project Type and Purpose
- This is a Next.js–based full-stack (build-time) application with a React frontend that delivers a static-style UI for security analysts to look up Windows Security and Sysmon events.
- It has no live database or external API at runtime; instead it ships pre-processed JSON data baked in at build time.

##### File Structure
- Top-level config files (next.config.mjs, tsconfig.json, tailwind.config.ts) define the build and styling environment.
- The `process_stix.py` script lives at root and is used offline to convert the MITRE STIX bundle into a clean JSON file (`src/data/mitre_processed/techniques.json`).
- `src/data` contains raw event JSON plus TypeScript mapping files (`categories.ts`, `mitre.ts`, `scenarios.ts`).
- `src/app/page.tsx` orchestrates server-side data loading and merging logic during Next.js’s build/SSR phase.
- `src/components` holds the React UI elements (search bar, event list, detail view, MITRE tabs).
- There is no separate “database” layer; all data lives in JSON files under `src/data`.

##### Key Insights from README
- Data sources are: Microsoft docs–derived JSON, manual TS mapping files, and a processed STIX JSON (from the Python script).
- Build logic merges these data sets into a unified “EventDetail” object per event, which is passed as props to the React components.
- The live site is deployed on Vercel and served as a static/SSR hybrid with client-side search interactivity.

##### Main Components
a. Data Sources Layer
- Raw Event JSON (`sysmon_events.json`, `windows_events.json`)
- Manual TS Mappings (`categories.ts`, `mitre.ts`, `scenarios.ts`)
- MITRE STIX Processor (`process_stix.py`) → `techniques.json`
b. Build/Server Layer (Next.js)
- next.config.mjs, tailwind.config.ts
- `src/app/page.tsx`: loads and merges all data at build/SSR time
c. Frontend Layer
- React Components in `src/components` (Header, Footer, EventCard, EventDetailView, MitreTabs, etc.)
- Client-side search/filter logic in `EventSearchClient.tsx`
- Styling with Tailwind CSS
d. Deployment Layer
- Vercel hosting (CDN, static assets)

##### Relationships and Data Flows
- The Python script ingests the official STIX bundle and outputs `techniques.json`.
- At build/SSR time, Next.js reads the raw event JSON + TS mappings + `techniques.json` → merges into enriched event objects.
- The merged data is serialized into the HTML/JS payload and sent to the client.
- The React components render the UI and implement client-side filtering/search.
- User actions (search, filter, select) drive in-browser state changes; no further server calls occur.

##### Architectural Patterns and Principles
- ETL Pipeline Pattern: offline Python script + build‐time merge
- Unidirectional Data Flow: data moves raw→merged→props→UI
- Component-Based UI: each view element is a reusable React component
- Static/SSR Hybrid: Next.js generates HTML at build/SSG or on request, then hydrates to a SPA

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources Layer
    subgraph "Build Time: Data Sources"
        direction TB
        STIX["process_stix.py"]:::build
        STIX -->|ETL→| Techniques["[(techniques.json)]"]:::data
        Sysmon["[(sysmon_events.json)]"]:::data
        Windows["[(windows_events.json)]"]:::data
        Categories["[(categories.ts)]"]:::data
        MitreMap["[(mitre.ts)]"]:::data
        Scenarios["[(scenarios.ts)]"]:::data
    end

    %% Build & Server Layer
    subgraph "Build Time: Next.js Build"
        direction TB
        Config["next.config.mjs"]:::build
        Tailwind["tailwind.config.ts"]:::build
        GlobalsCSS["globals.css"]:::build
        Types["index.ts"]:::build
        Page["page.tsx"]:::build
        Layout["layout.tsx"]:::build
    end

    %% Build Data Flow
    subgraph "Build Process"
        direction TB
        Techniques & Sysmon & Windows & Categories & MitreMap & Scenarios -->|"Merge Data"| Page
        Config & Tailwind & GlobalsCSS & Types & Layout --> Page
        Page -->|"Build→HTML/JS Bundle"| Bundle["Next.js Output"]:::build
    end

    %% Runtime Layer
    subgraph "Runtime: Client Browser"
        direction TB
        Bundle --> UI["React Components"]:::frontend
        subgraph "UI Components"
            direction TB
            Header["Header"]:::frontend
            Footer["Footer"]:::frontend
            Search["EventSearchClient.tsx"]:::frontend
            Card["EventCard"]:::frontend
            Detail["EventDetailView"]:::frontend
            Tabs["MitreTabs"]:::frontend
        end
        Search -->|User Action→| Card
        Card -->|Select Event→| Detail
    end

    %% Deployment Layer
    subgraph "Deployment"
        direction TB
        Vercel["Vercel CDN"]:::infra
        Bundle --> Vercel
        Vercel --> Bundle
    end

    %% Legend
    subgraph "Legend"
        direction TB
        A[("Data Files/Stores")]:::data
        B[("Build/Server")]:::build
        C[("Frontend/UI")]:::frontend
        D[("Deployment/Infra")]:::infra
    end

    %% Click Events
    click Sysmon "https://github.com/packetwarden/wetnav/blob/main/src/data/sysmon_events.json"
    click Windows "https://github.com/packetwarden/wetnav/blob/main/src/data/windows_events.json"
    click Categories "https://github.com/packetwarden/wetnav/blob/main/src/data/mappings/categories.ts"
    click MitreMap "https://github.com/packetwarden/wetnav/blob/main/src/data/mappings/mitre.ts"
    click Scenarios "https://github.com/packetwarden/wetnav/blob/main/src/data/mappings/scenarios.ts"
    click STIX "https://github.com/packetwarden/wetnav/blob/main/process_stix.py"
    click Techniques "https://github.com/packetwarden/wetnav/blob/main/src/data/mitre_processed/techniques.json"
    click Config "https://github.com/packetwarden/wetnav/blob/main/next.config.mjs"
    click Tailwind "https://github.com/packetwarden/wetnav/blob/main/tailwind.config.ts"
    click GlobalsCSS "https://github.com/packetwarden/wetnav/blob/main/src/app/globals.css"
    click Page "https://github.com/packetwarden/wetnav/blob/main/src/app/page.tsx"
    click Layout "https://github.com/packetwarden/wetnav/blob/main/src/app/layout.tsx"
    click Header "https://github.com/packetwarden/wetnav/blob/main/src/components/Header.tsx"
    click Footer "https://github.com/packetwarden/wetnav/blob/main/src/components/Footer.tsx"
    click Card "https://github.com/packetwarden/wetnav/blob/main/src/components/EventCard.tsx"
    click Detail "https://github.com/packetwarden/wetnav/blob/main/src/components/EventDetailView.tsx"
    click Tabs "https://github.com/packetwarden/wetnav/blob/main/src/components/MitreTabs.tsx"
    click Search "https://github.com/packetwarden/wetnav/blob/main/src/components/EventSearchClient.tsx"
    click Types "https://github.com/packetwarden/wetnav/blob/main/src/types/index.ts"

    %% Styles
    classDef data fill:#bfdbfe,color:#1e3a8a,stroke:#93c5fd;
    classDef build fill:#d1fae5,color:#065f46,stroke:#6ee7b7;
    classDef frontend fill:#fef3c7,color:#78350f,stroke:#fcd34d;
    classDef infra fill:#e5e7eb,color:#374151,stroke:#9ca3af;
```
