DocOps Headquarters

The central command center for Policy as Code (PaC) and Infrastructure as Code (IaC)

DocOps is a comprehensive system that transforms documentation from static files into an active headquarters managing living projects. It enforces policies, generates configurations, detects drift, and maintains consistency across your entire engineering organization.

🎯 Vision

Transform from "documentation with embedded patterns" to an "active headquarters that manages living projects."

🚀 Quick Start

Prerequisites

See INSTALL.md for complete installation instructions.

Required:

• Bun 1.2+
• Git
• Node.js 18+

Check your system:

bash scripts/check-tools.sh

Install DocOps

# Clone the headquarters
git clone https://github.com/verlyn13/doc-system.git
cd doc-system

# Install and build the CLI
cd cli
bun install
bun run build
cd ..

# Verify installation
node cli/dist/index.js --help

# Initialize a new project
node cli/dist/index.js init

📁 Repository Structure

doc-system/
├── cli/                   # DocOps CLI implementation
├── templates/             # Reusable project templates
│   ├── base/             # Core templates for all projects
│   ├── stacks/           # Stack-specific templates
│   └── components/       # Modular components
├── schemas/              # JSON schemas for validation
├── examples/             # Example projects
├── .github/workflows/    # CI/CD workflows
├── legacy/               # Original documentation (archived)
└── project-brief.md      # Project overview for Windsurf

🛠️ Core Components

1. DocOps CLI

• docops init - Initialize new projects with interactive setup
• docops generate - Generate configurations from project profile
• docops validate - Validate setup and check for drift

2. Templates System

• Base Templates: Core configurations used by all projects
• Stack Templates: Pre-configured for TypeScript/Next.js, Python/FastAPI
• Template Inheritance: Stack templates extend base templates

3. Project Profile

The single source of truth driving all automation:

{
  "version": "2.1.0",
  "name": "my-project",
  "stack": {
    "runtime": { "engine": "bun", "language": "typescript" },
    "database": { "type": "postgresql", "orm": "prisma" }
  }
}

🎨 Supported Stacks

TypeScript + Next.js

• Bun runtime with TypeScript
• Next.js 15 + React 19
• Tailwind CSS 4
• Prisma ORM
• Vercel hosting

Python + FastAPI

• Python 3.13+ with modern tooling
• FastAPI + SQLModel
• uv package manager
• ruff + mypy linting
• Docker deployment ready

🔄 Workflow

1. Initialize: docops init creates project from template
2. Configure: Update docs/project.profile.json with your specifics
3. Generate: docops generate creates all configurations automatically
4. Validate: docops validate checks for issues and drift

📊 Key Features

Profile-Driven Generation

Everything generates from docs/project.profile.json:

• CI/CD workflows (.github/workflows/docops.yml)
• Environment templates (.env.example)
• Documentation structure (docs/README.md)
• Tool configurations (bunfig.toml, prisma/schema.prisma)
• Policy enforcement (docops.policy.json)

Policy as Code

• JSON schema validation for all configurations
• Environment file security scanning
• Documentation freshness requirements
• Generated file validation

Modern Toolchain

• TypeScript: Bun runtime, Biome linting
• Python: uv, ruff, mypy, Python 3.13+
• Infrastructure: Cloudflare, Vercel, Terraform-ready
• CI/CD: GitHub Actions with automated validation

🧪 Development

CLI Development

cd cli

# Install dependencies
bun install

# Run in development mode
bun run dev -- init --help

# Run tests
bun test

# Lint and format
bun run lint
bun run format

# Build for distribution
bun run build

Testing the CLI

# Test initialization in a temp directory
cd /tmp
node /path/to/doc-system/cli/dist/index.js init

# Test generation
node /path/to/doc-system/cli/dist/index.js generate

# Test validation
node /path/to/doc-system/cli/dist/index.js validate

📚 Documentation

• Project Brief - Complete overview for Windsurf
• CLI Documentation - CLI usage and development
• Templates Guide - Template system overview
• Example Projects - Reference implementations

🚧 Current Status

✅ Completed

• Template extraction and organization
• Functional CLI with core commands (init, generate, validate)
• JSON schemas for validation
• Basic CI/CD workflow
• Unit tests for core functionality
• Lint/format configuration

🚧 In Progress

• Additional stack templates
• Enhanced drift detection
• Auto-fix capabilities

📋 Planned

• Project registry and telemetry
• Template marketplace
• Multi-org support
• Advanced policy engines

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run bun run lint and bun test in the cli/ directory
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

MIT - See LICENSE file for details.

🙏 Acknowledgments

Built with modern tools and best practices from the open-source community.

---

DocOps Headquarters - Where documentation becomes operational.