Welcome to the BuildAIOS documentation.
This directory contains the technical documentation, architectural designs, project planning, and engineering decisions for the BuildAIOS ecosystem.
docs/
├── architecture/ # System architecture and design documents
├── project/ # Current project status, plans, and progress
├── proposals/ # Future ideas and RFC-style proposals
├── roadmap/ # Development roadmap and milestones
├── decisions/ # Architecture Decision Records (ADRs)
├── diagrams/ # Images and architecture diagrams
|-- Roles/
└── README.md
This directory defines the engineering ownership within the BuildAIOS project.
Roles describe responsibilities, not specific people.
Contributors may change over time, but these responsibilities remain stable.
- Runtime
- MCP Gateway
- Website
- Documentation
- Security
- Infrastructure
- Community
- Release Management
Each document explains:
- Purpose
- Responsibilities
- Deliverables
- Dependencies
- Required skills
Core technical documentation describing how BuildAIOS is designed.
Examples:
- System Architecture
- Runtime Design
- MCP Gateway
- Agent Lifecycle
- Trust & Security
- Environment Packs
Living documents that describe the current state of development.
Examples:
- CURRENT_STATE.md
- NEXT_ACTIONS.md
- OPERATING_PLAN.md
- TEAM_STRUCTURE.md
- DEVELOPMENT_STATUS.md
These documents change frequently as development progresses.
Design proposals and future ideas that are under discussion.
Examples:
- Scheduler Improvements
- Marketplace Concepts
- Multi-node Architecture
- New Agent Types
- Experimental Features
A proposal is not considered part of the official architecture until accepted.
Project planning and milestone tracking.
Examples:
- Phase 1
- Phase 2
- Release Planning
- Long-term Vision
Architecture Decision Records (ADRs).
Each ADR documents:
- The problem
- Available options
- Decision taken
- Rationale
- Consequences
Once recorded, ADRs serve as the historical record of major engineering decisions.
Architecture diagrams, flowcharts, and visual documentation used throughout the project.
If you're new to BuildAIOS, we recommend reading the documentation in the following order:
- Project Overview (Repository README)
- Architecture
- Project Status
- Roadmap
- Proposals
- ADRs
The documentation follows a few simple rules:
- Architecture describes how the system works.
- Project describes what is currently being built.
- Roadmap describes what comes next.
- Proposals describe ideas that may change.
- ADRs explain why important decisions were made.
Keeping these concerns separate helps the documentation remain clear, maintainable, and easy to navigate.
Happy building! 🚀