Skip to content

SYSTEM README

Jump to bottom
Thomas Mangin edited this page Nov 10, 2025 · 4 revisions

ExaBGP Documentation - Claude Code System

Project: ExaBGP Wiki Documentation Location: /common/wiki/ Purpose: Comprehensive documentation for ExaBGP BGP implementation

Project Context

This is the ExaBGP documentation project, creating comprehensive wiki documentation covering:

  • Getting Started guides
  • API documentation (Text and JSON)
  • Configuration syntax and directives
  • Address families (FlowSpec, EVPN, BGP-LS, L3VPN, etc.)
  • Use cases (DDoS mitigation, anycast, high availability, load balancing)
  • Operations guides (debugging, monitoring, performance)
  • Integration guides (Docker, Kubernetes, commercial solutions)

Key Principle: ExaBGP does NOT manipulate RIB/FIB - this must be emphasized throughout documentation.

🔴 CRITICAL: Factual Accuracy Requirement

ONLY document factual information that can be verified:

Information Sources (in order of priority):

  1. ExaBGP source code - /common/exabgp/ and /main/src/exabgp/
  2. RFC specifications - Cited in RFC-SUPPORT.md and RFC-Information.md
  3. Official vendor documentation - Cisco, Juniper, Arista docs (with links)
  4. Verified external sources - APNIC articles, vendor blogs, academic papers
  5. Project maintainer input - Thomas Mangin's guidance
  6. Configuration examples - /main/etc/exabgp/ (98 examples)

Verification Requirements:

  • ✅ DO: Document features that exist in the codebase

  • ✅ DO: Cite RFC specifications with RFC numbers

  • ✅ DO: Link to vendor documentation for vendor-specific behavior

  • ✅ DO: Acknowledge when behavior varies by vendor/platform

  • ✅ DO: Warn users to test on their specific equipment

  • ✅ DO: Correct errors immediately when discovered (as we did with rate-limit)

  • ❌ DON'T: Invent features that don't exist

  • ❌ DON'T: Claim capabilities without verification

  • ❌ DON'T: Document commercial products without clear labeling

  • ❌ DON'T: Make absolute statements about vendor behavior without testing

  • ❌ DON'T: Assume behavior - verify in code or documentation

When Uncertain:

  1. Check the source code first
  2. Search external documentation (vendor docs, RFCs, blog posts)
  3. Ask the project maintainer (Thomas)
  4. Mark as "needs verification" if documentation must be written before confirmation
  5. Use qualifying language: "may", "typically", "on some platforms", "according to RFC X"

Corrections Process:

When factual errors are discovered:

  1. Acknowledge the error immediately
  2. Verify the correct information from authoritative sources
  3. Update all affected documentation comprehensively
  4. Document the correction in git commit messages
  5. Update this system file with the corrected facts

Recent Corrections (Learn From These):

  • Rate-limit units: Corrected "per source" → NOT per-source; RFC 5575 bytes/sec, vendors differ
  • ElastiFlow: Removed (commercial product, not freely available)
  • Wanguard status: Corrected from "no longer uses ExaBGP" → has BGP Connector integration
  • Akvorado categorization: Clarified as flow collector, NOT DDoS detection solution

Remember: User trust depends on accuracy. When in doubt, verify or acknowledge uncertainty.

Project Status

Documentation Progress: ✅ COMPLETE (95 wiki files, ~62,000 lines)

  • Phase 0: Research (11 knowledge base files in .claude/)
  • Phase 1: Setup & Infrastructure ✅
  • Phase 2: Tier 1 Critical Documentation ✅
  • Phase 3: Tier 2 Important Documentation ✅
  • Phase 4: Tier 3 Enhancement Documentation ✅
  • Phase 5: Reference & Polish ✅

Key Tracker: .claude/CLAUDE.md - comprehensive progress tracking

Important Files

Documentation Trackers (in .claude/)

  • CLAUDE.md - Master progress tracker (session info, completed work, next actions)
  • DOCUMENTATION-PLAN.md - Original master plan with all 75 planned files
  • SYSTEM-README.md - This file (system reference for Claude Code sessions)

User Documentation (in wiki root)

  • RFC-SUPPORT.md - RFC compliance reference (published to wiki)
  • RFC-Information.md - Detailed RFC implementation list (published to wiki)

Code Structure

  • /common/wiki/ - All documentation (where you are now)
  • /common/exabgp/ - ExaBGP source code to document
  • /main/src/exabgp/ - Main ExaBGP source
  • /main/etc/exabgp/ - 98 configuration examples

Key Documentation Principles

Every Document Must Include:

  1. Clear table of contents
  2. Practical examples from etc/exabgp/ configs
  3. Cross-references to related docs
  4. "See Also" section
  5. Code examples with explanations
  6. Common errors and solutions
  7. Claude acknowledgment at bottom: **👻 Ghost written by Claude (Anthropic AI)**

Writing Style:

  • Beginner-friendly for Getting Started
  • Technical but clear for API/Configuration
  • Practical examples in every use case
  • Cross-link extensively

GitHub Wiki Link Format:

  • Internal links: NO .md extension
  • Example: [FlowSpec](Address-Families-FlowSpec-FlowSpec-Overview) not [FlowSpec](Address-Families-FlowSpec-FlowSpec-Overview.md)

Emoji Usage Guidelines:

ONLY use emojis if the user explicitly requests it, OR for specific functional purposes:

Functional Use (Appropriate):

  • ⚠️ - Warnings about vendor differences, implementation issues, critical caveats
  • ✅ - Confirmation of supported features, capabilities, correct approaches
  • ❌ - Things ExaBGP cannot do, incorrect approaches, unsupported features
  • 🔴 - Critical/urgent warnings (e.g., "CRITICAL: Factual Accuracy Requirement")
  • ⭐ - Highlight significant facts (e.g., "ExaBGP was the FIRST open-source FlowSpec")
  • 📚 - References to other documentation sections
  • 🛡️ - Security-related content, DDoS mitigation sections
  • 💡 - Important notes or tips
  • 🎉 - Project milestones in CLAUDE.md (e.g., "PROJECT COMPLETE")
  • 👻 - Claude acknowledgment footer: **👻 Ghost written by Claude (Anthropic AI)**
  • 🤖 - Git commit attribution: 🤖 Generated with [Claude Code](...)

Status Tracking (CLAUDE.md only):

  • ✅ - Completed tasks/phases
  • ⏳ - In progress tasks
  • 📊 - Statistics/metrics

Inappropriate Use:

  • ❌ Don't use emojis for decoration or emphasis in technical content
  • ❌ Don't add emojis to code examples or configuration snippets
  • ❌ Don't use emojis in section headers unless they serve a functional purpose
  • ❌ Don't use emotional/expressive emojis (😊, 🚀, 🔥, etc.) unless user requests

Rationale: Emojis serve as visual markers for:

  1. Critical warnings that users must not miss
  2. Clear yes/no distinctions (supported vs unsupported features)
  3. Content categorization (security, references, notes)
  4. Status tracking in progress documents

Keep emoji usage minimal, functional, and consistent. Technical documentation should be clear without relying on emojis.

Key Technical Facts (IMPORTANT!)

ExaBGP Core Behavior

  • Does NOT manipulate RIB/FIB - pure BGP protocol implementation
  • External processes handle route installation via API
  • 55+ RFCs implemented (protocol level)
  • Proven at hyperscale (Facebook/Meta Katran)

FlowSpec Rate-Limit (Critical!)

  • RFC 5575: Specifies bytes per second
  • Juniper: Converts to bits/sec internally (×8 multiplication)
  • Cisco: May interpret differently by platform
  • Rate-limit is NOT per-source - applied to matching traffic per vendor implementation
  • Always warn users to test on their specific equipment!

DDoS Detection Solutions

  • Open-source: FastNetMon Community (native ExaBGP support)
  • Commercial: FastNetMon Advanced, Wanguard (has ExaBGP integration via BGP Connector)
  • Flow tools: Akvorado (flow collector, NOT DDoS detection), pmacct, nfdump/nfsen
  • ElastiFlow: Removed (commercial product, not appropriate for OSS docs)

Vendor Products

Research Knowledge Base

The .claude/ directory contains 11 research files (188KB, 6,229 lines):

  • README.md - Research index (existing file for documentation writers)
  • use-cases-summary.md - 9 major use cases
  • architecture-overview.md - Technical deep-dive
  • resources/ - API reference, FlowSpec patterns, HA architectures, user stories, etc.

Note: These are research documents for documentation writers, not end-user documentation.

External Resources

Git Workflow

  • Main branch: master
  • Commit format: Descriptive message with Claude Code attribution
  • Always include: 🤖 Generated with [Claude Code](https://claude.com/claude-code)
  • Co-author: Co-Authored-By: Claude <[email protected]>

Session Continuity

For continuing work in future sessions:

  1. Read .claude/CLAUDE.md for latest status and next actions
  2. Check recent git commits for what was just completed
  3. Reference .claude/DOCUMENTATION-PLAN.md for overall structure
  4. Review this file (.claude/SYSTEM-README.md) for key technical facts
  5. Update .claude/CLAUDE.md with progress when completing major work

File Organization

.claude/ directory - Claude Code internal files (NOT published to wiki):

  • CLAUDE.md - Progress tracker
  • DOCUMENTATION-PLAN.md - Master plan
  • SYSTEM-README.md - System reference
  • README.md - Research index
  • architecture-overview.md - Technical research
  • use-cases-summary.md - Use case research
  • resources/ - Research materials (11 files total)
  • commands/ - Future: slash commands
  • templates/ - Future: reusable templates
  • docs/ - Future: system documentation

Wiki root - Published documentation only:

  • Home.md - Main navigation hub
  • _Sidebar.md - Navigation sidebar
  • RFC-SUPPORT.md - RFC compliance (user-facing)
  • RFC-Information.md - RFC details (user-facing)
  • All other .md files and subdirectories - User documentation

System Version: 1.0.0 Last Updated: 2025-11-10 Model: Claude Sonnet 4.5

🏠 Home

🚀 Getting Started

🔧 API

🛡️ Use Cases

🌐 Address Families

⚙️ Configuration

🔍 Operations

📚 Reference

🔄 Migration

🌍 Community

🔗 External

👻 Ghost written by Claude (Anthropic AI)

Clone this wiki locally