Documentation Organization#

CipherSwarm organizes its documentation in the docs/ directory, using a modular structure that separates content by audience and purpose. The main categories include phase-based specification files, testing guides, developer guides, and migration plans.

Phase-Based Specification Files#

Project phases are documented as individual Markdown files or subdirectories under docs/v2_rewrite_implementation_plan/. Each phase (e.g., core infrastructure, API implementation, resource management, web UI, deployment, task distribution, monitoring/testing/documentation, TUI development) has a dedicated file such as phase-1-core-infrastructure.md, phase-2-api-implementation.md, and so on. This approach enables incremental, modular documentation that aligns with the project's development lifecycle. Each phase document outlines goals, tasks, and links to related guides or implementation notes, supporting clear traceability and maintainability as the architecture evolves [source].

Testing Guides#

Testing documentation is organized by phase and feature. For example, the end-to-end (E2E) test coverage plan is documented in phase-3-e2e-test-coverage-plan.md, which details testing strategies, missing coverage, test priorities, and infrastructure requirements. The guides cover backend, frontend, and integration tests, and include explicit test case identifiers and descriptions for each functional area (authentication, dashboard, campaign management, attack configuration, resource management, agent management, user/project management, access control, monitoring, notifications, UI/UX, integration, performance) [source].

Developer Guides#

Developer-facing documentation is found in docs/development/, including a style guide (style-guide.md), user journey flowcharts, and contributing guidelines. These documents describe code conventions, architectural patterns, and onboarding instructions.

CipherSwarm also maintains root-level documentation files for developers and AI agents:

• AGENTS.md: High-level guidance for AI agents and developers working with the codebase, covering project overview, architecture, state machines, testing strategy, and development workflow. Focuses on architectural patterns and workflow guidance, with implementation details and edge cases extracted to GOTCHAS.md. Cross-references the gotchas file for detailed patterns and pitfalls. Approximately 560 lines of gotchas and implementation details have been moved to the dedicated file, streamlining the main guide while maintaining comprehensive coverage through cross-references.
• GOTCHAS.md: Centralizes edge cases, hard-won lessons, and "watch out for" patterns organized by domain (State Machines, Testing, API & rswag, Database & ActiveRecord, Infrastructure). Referenced from AGENTS.md to keep the main guide concise while preserving critical knowledge. This 203-line dedicated file now includes gotchas previously embedded in AGENTS.md, particularly around benchmarking, database constraints (unique index cleanup for migrations), ActiveRecord patterns (upsert_all behavior in Rails 8.1+, including the requirement for ALL NOT NULL columns in upsert_all payloads when using unique_by: :id even with update_only), state machine edge cases, CI test scope, Turbo Stream patterns, and infrastructure tips (Redis locks, logging patterns). The reorganization improves separation of concerns: AGENTS.md provides architectural overview and workflow, while GOTCHAS.md captures implementation pitfalls and testing patterns.

The API documentation is generated automatically from RSpec request tests using Rswag, ensuring that API docs remain in sync with the codebase. The vacuum OpenAPI linter validates the generated OpenAPI specification for compliance with OpenAPI 3.0 standards.

When writing RSwag API specs, use request_body_json schema: {...}, examples: :let_name for request bodies. This helper must be called inside the HTTP method block (post, put, patch), not at the path level, for proper OpenAPI 3.0 requestBody generation. The request_body_json helper is a polyfill added for rswag 3.0.0.pre, as this DSL does not exist natively in the current pre-release version. It wraps the consumes + parameter in: :body mechanism so specs use the OpenAPI 3.0 requestBody DSL while the formatter converts to valid output.

The rswag 3.0.0.pre migration includes several compatibility shims:

• spec/support/rswag_polyfills.rb: Contains rswag 3.x polyfills including the request_body_json DSL for request body definitions, LetFallbackHash for parameter resolution compatibility with existing let blocks, and a RequestFactoryLetFallback module that maintains rswag 2.x let-based parameter lookup behavior. A version guard ensures the polyfills fail loudly if rswag is upgraded to a stable 3.x release, prompting removal of the polyfill file.

• spec/openapi_helper.rb: A shim file that delegates to swagger_helper.rb to maintain backward compatibility. rswag 3.x loads openapi_helper.rb by default; this shim ensures existing specs and CI scripts continue to work without modification.

• spec/swagger_helper.rb: The main rswag configuration file containing OpenAPI/Swagger settings. For rswag 3.0.0.pre, openapi_strict_schema_validation has been replaced with granular options: openapi_no_additional_properties (rejects undeclared response properties) and openapi_all_properties_required (treats every declared property as required). The configuration loads the polyfills from spec/support/rswag_polyfills.rb [source].

Migration Plans#

Migration plans are documented as standalone Markdown files, such as psycopg_migration.md under docs/v2_rewrite_implementation_plan/side_quests/. These files outline step-by-step migration tasks, success criteria, and compatibility notes, supporting safe and auditable transitions for dependencies, database drivers, or infrastructure [source].

Deployment Guides#

Deployment documentation is organized under docs/deployment/ and covers production configuration, environment setup, and deployment strategies:

• Environment Variables Reference (environment-variables.md): Comprehensive reference covering all environment variables categorized by requirement level (Critical, Important, Optional, S3 Storage). Each variable includes purpose, default values, production requirements, examples, and common configuration mistakes. This 855-line guide documents four deployment scenarios (single-server, multi-server, air-gapped, development) and includes troubleshooting for common configuration issues. Created to prevent production failures due to undocumented variables such as APPLICATION_HOST (required for mailers) and DISABLE_SSL (for reverse proxy setups). The guide is essential reading for any production deployment and complements the .env.example template.

• Air-Gapped Deployment Guide (air-gapped-deployment.md): Step-by-step instructions for deploying in isolated lab environments without Internet access, including local storage configuration and environment variable setup.

• Production Load Balancing (production-load-balancing.md): Nginx load balancing with horizontal web scaling for multi-server deployments.

• Connection Pool Sizing (connection-pool-sizing.md): PostgreSQL connection pool sizing formula, per-process defaults, and scaling calculations for single-server through 20-agent deployments. Covers max_connections configuration, PgBouncer guidance for high-connection deployments, and integration with the Prometheus monitoring stack to alert on pool exhaustion.

• Monitoring Setup (monitoring-setup.md): Step-by-step setup of the optional Prometheus + Grafana monitoring stack (docker-compose-monitoring.yml). Covers the opt-in METRICS_ENABLED flag, air-gapped pre-pull workflow using docker save/docker load, pre-provisioned dashboards, and the full alert ruleset (Sidekiq, PostgreSQL connection pool, Redis, Rails 5xx error rate). Designed for isolated lab and secure environments with no Internet connectivity.

Deployment guides cross-reference the environment variables reference and include validation steps to ensure correct configuration before production use.

MkDocs Integration#

CipherSwarm uses MkDocs with the Material theme to generate a professional, searchable, and mobile-responsive documentation site. The documentation structure is defined in mkdocs.yml, which organizes navigation into logical sections: Home, Getting Started, User Guide, Administrator Manual, API Reference, and Development. Each section maps to directories and Markdown files in docs/ [source].

Example directory structure:

docs/
├── index.md
├── getting-started/
│ ├── quick-start.md
│ └── installation.md
├── user-guide/
│ ├── agent-setup.md
│ ├── web-interface.md
│ ├── attack-configuration.md
│ ├── resource-management.md
│ ├── optimization.md
│ ├── common-issues.md
│ └── faq.md
├── admin/
│ ├── installation.md
│ ├── configuration.md
│ ├── user-management.md
│ ├── monitoring.md
│ ├── security.md
│ └── troubleshooting.md
├── api/
│ ├── api-reference-agent-auth.md
│ └── control-api.md
├── deployment/
│ ├── environment-variables.md
│ ├── air-gapped-deployment.md
│ ├── production-load-balancing.md
│ ├── connection-pool-sizing.md
│ └── monitoring-setup.md
└── development/
    ├── style-guide.md
    └── contributing.md

The mkdocs.yml file configures navigation and enables features such as navigation tabs, integrated table of contents, and advanced search:

site_name: CipherSwarm Documentation
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - search.suggest
    - search.highlight

nav:
  - Home: index.md
  - Getting Started:
      - Quick Start: getting-started/quick-start.md
      - Installation: getting-started/installation.md
  - User Guide:
      - Agent Setup: user-guide/agent-setup.md
      # ... (other user guide files)
  # ... (other sections)

[source]

Docker and CI/CD Integration#

MkDocs is integrated into the Docker Compose stack using the official squidfunk/mkdocs-material image. The documentation service mounts the local docs/ directory and mkdocs.yml, exposing the site on port 8001. This setup allows developers to preview documentation locally and ensures consistency across environments. The CI/CD pipeline validates documentation on every pull request, running Vale linting for style and MkDocs build verification. Optionally, documentation can be deployed to GitHub Pages [source].

Example Docker Compose service:

docs:
  image: squidfunk/mkdocs-material:latest
  volumes:
    - ./docs:/docs
    - ./mkdocs.yml:/docs/mkdocs.yml
  ports:
    - "8001:8000"
  command: serve --dev-addr=0.0.0.0:8000

AI Instruction Sync#

CipherSwarm uses AI instruction sync and code review automation via a .coderabbitai.yaml configuration file. This file defines tone, labeling, path-specific review instructions, and automated checks for documentation quality, code style, and test coverage. The configuration enforces standards for YARD documentation, RSpec tests, API documentation, and commit message formatting. It also integrates with tools like Vale for style linting and supports automated review workflows in CI/CD [source].

AI instruction sync ensures that documentation and code reviews follow consistent, actionable guidelines, with pre-merge checks for docstrings, unit tests, and commit message compliance. This helps maintain alignment between documentation and the evolving architecture.

Best Practices for Documentation Maintenance#

CipherSwarm follows several best practices to ensure documentation remains accurate and aligned with the architecture:

• Organize documentation by logical sections and project phases, using dedicated files and directories for each audience and purpose.
• Keep documentation up to date with development milestones, especially during major upgrades or migrations.
• Use automated tools (Vale, MkDocs build checks, vacuum OpenAPI linter, AI review bots) to enforce style, structure, and completeness.
• Integrate documentation validation into the CI/CD pipeline to catch issues early. The vacuum OpenAPI linter is enforced via the lint_api GitHub Actions job and validates generated OpenAPI/Swagger documentation for compliance with OpenAPI 3.0 standards. A custom ruleset (vacuum-ruleset.yaml) disables rules that conflict with Rails conventions (snake_case properties, underscore paths) and RSwag design patterns. Vacuum runs as part of automated CI checks and reports quality scores. Run just lint-api locally to validate the OpenAPI specification.
• Encourage contributions by providing clear guidelines, examples, and a consistent structure.
• Update navigation and cross-references as new sections are added or reorganized.
• Maintain migration guides and upgrade plans as living documents, updating them with each architectural change.
• Ensure API documentation is generated from source code and tests to prevent drift.
• Use phase-based specification files to document incremental changes and maintain traceability throughout the project lifecycle [source].

By following these practices, CipherSwarm maintains high-quality, accessible, and up-to-date documentation that supports both users and developers as the system evolves.