Skip to content

docs: Break up advanced technical reference into sub-pages with index #9

Description

@dkontango

Problem

Each advanced doc is 400-600+ lines with 7-12 mermaid diagrams. That's a lot of content per page. Readers looking for a specific topic (e.g., "how does JA4 Section B hashing work?") have to scroll through unrelated material to find it.

Proposal

  1. Break each advanced doc into focused sub-pages — one concept per page, ~100-200 lines max
  2. Create docs/advanced/README.md — styled index page with navigation, descriptions, and a fun "enter if you dare" vibe
  3. Organize by topic area with clear hierarchy

Proposed structure

docs/advanced/
├── README.md                    ← styled index ("enter if you dare")
├── tls/
│   ├── clienthello-format.md    ← byte layout, record header, handshake structure
│   ├── ja4-fingerprinting.md    ← JA4 computation, sections A/B/C, worked example
│   ├── grease-filtering.md      ← GREASE pattern, why it matters
│   └── replay-conn.md           ← peek-without-consuming pattern
├── hp/
│   ├── overview.md              ← levels, thresholds, philosophy
│   ├── drain-heal.md            ← event costs, regeneration math
│   ├── attack-scenarios.md      ← simulations, timelines, recovery
│   └── tuning.md                ← config knobs, traffic pattern recommendations
├── rules/
│   ├── matching.md              ← SNI wildcards, JA4 lists, CIDR, AND logic
│   ├── ordering.md              ← rule priority, catch-all placement
│   ├── rate-limiting.md         ← rate strings, HP multiplier, window epochs
│   └── examples.md              ← 5-connection walkthrough
├── storage/
│   ├── boltdb-buckets.md        ← bucket layout, key formats
│   ├── encoding.md              ← JSON vs binary, float64 persistence
│   └── rate-windows.md          ← window epoch calculation, cleanup
├── ziti/
│   ├── identity.md              ← loading, dial-only model, policy enforcement
│   ├── dial-lifecycle.md        ← controller lookup, circuit establishment
│   ├── relay-bridge.md          ← replayConn, half-close, bidirectional copy
│   └── shutdown.md              ← drain timeout, graceful close
└── ops/
    ├── memory-budget.md         ← per-connection breakdown, goroutine model
    ├── bottlenecks.md           ← BoltDB writer, Ziti dial latency, fd limits
    └── tuning.md                ← MaxConnections, ReadTimeout, HP thresholds

Acceptance criteria

  • Each sub-page is ≤200 lines
  • Each sub-page has back-navigation to the advanced index
  • docs/advanced/README.md has styled index with mermaid topic map
  • Original 6 monolithic docs removed
  • README.md advanced section updated to point at new index
  • All mermaid diagrams preserved (redistributed across sub-pages)
  • Zero internal infrastructure references
  • Consistent color palette across all diagrams

🤖 Generated with Claude Code

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions