Skip to content

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

@dkontango

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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions