199 lines
7.4 KiB
Markdown
199 lines
7.4 KiB
Markdown
# Attune Documentation
|
|
|
|
Welcome to the Attune project documentation! This directory contains comprehensive documentation for the Attune automation and orchestration platform.
|
|
|
|
## 📚 Quick Navigation
|
|
|
|
### Getting Started
|
|
- **[Quick Start Guide](guides/quick-start.md)** - Get up and running quickly
|
|
- **[Workspace Setup](development/WORKSPACE_SETUP.md)** - Set up your development environment
|
|
- **[Configuration Guide](configuration/configuration.md)** - Configure Attune services
|
|
|
|
### Core Concepts
|
|
- **[Architecture Overview](architecture/)** - System design and service architecture
|
|
- **[Workflow Engine](workflows/workflow-execution-engine.md)** - How workflows are executed
|
|
- **[Pack System](packs/pack-structure.md)** - Understanding automation packs
|
|
- **[Sensors & Triggers](sensors/)** - Event monitoring and triggering
|
|
|
|
### Development
|
|
- **[API Documentation](api/)** - REST API endpoint reference
|
|
- **[CLI Reference](cli/cli.md)** - Command-line interface guide
|
|
- **[Testing Guide](testing/running-tests.md)** - How to run and write tests
|
|
- **[Authentication](authentication/authentication.md)** - Auth mechanisms and security
|
|
|
|
### Operations
|
|
- **[Production Deployment](deployment/production-deployment.md)** - Deploy to production
|
|
- **[Operations Runbook](deployment/ops-runbook-queues.md)** - Troubleshooting and maintenance
|
|
- **[Performance Optimization](performance/QUICKREF-performance-optimization.md)** - Performance tuning
|
|
|
|
## 📁 Directory Structure
|
|
|
|
```
|
|
docs/
|
|
├── api/ # REST API documentation
|
|
├── architecture/ # System architecture and service design
|
|
├── authentication/ # Auth, security, and secrets management
|
|
├── cli/ # Command-line interface documentation
|
|
├── configuration/ # Configuration guides and troubleshooting
|
|
├── dependencies/ # Dependency management documentation
|
|
├── deployment/ # Production deployment and operations
|
|
├── development/ # Developer guides and tooling
|
|
├── examples/ # Example configurations and workflows
|
|
├── guides/ # Getting started guides and tutorials
|
|
├── migrations/ # Database migration documentation
|
|
├── packs/ # Pack system documentation
|
|
├── performance/ # Performance optimization guides
|
|
├── plans/ # Future planning and proposals
|
|
├── sensors/ # Sensor system documentation
|
|
├── testing/ # Testing strategies and guides
|
|
├── web-ui/ # Web UI documentation
|
|
├── webhooks/ # Webhook system documentation
|
|
└── workflows/ # Workflow engine documentation
|
|
```
|
|
|
|
## 🔍 Finding What You Need
|
|
|
|
### By Role
|
|
|
|
**I'm a new developer:**
|
|
1. Start with [Workspace Setup](development/WORKSPACE_SETUP.md)
|
|
2. Read the [Quick Start Guide](guides/quick-start.md)
|
|
3. Review [Architecture Overview](architecture/)
|
|
4. Learn about [Testing](testing/running-tests.md)
|
|
|
|
**I'm building a pack:**
|
|
1. Read [Pack Structure](packs/pack-structure.md)
|
|
2. Check [Examples](examples/)
|
|
3. Review [Pack Testing Framework](packs/pack-testing-framework.md)
|
|
4. See [Core Pack Integration](packs/core-pack-integration.md)
|
|
|
|
**I'm creating workflows:**
|
|
1. Start with [Workflow Quickstart](guides/workflow-quickstart.md)
|
|
2. Learn [Workflow Orchestration](workflows/workflow-orchestration.md)
|
|
3. Understand [Rule Parameter Mapping](workflows/rule-parameter-mapping.md)
|
|
4. Review [Execution Hierarchy](workflows/execution-hierarchy.md)
|
|
|
|
**I'm deploying to production:**
|
|
1. Read [Production Deployment](deployment/production-deployment.md)
|
|
2. Review [Configuration Guide](configuration/configuration.md)
|
|
3. Check [Security Review](authentication/security-review-2024-01-02.md)
|
|
4. Study [Operations Runbook](deployment/ops-runbook-queues.md)
|
|
|
|
**I'm using the API:**
|
|
1. Browse [API Documentation](api/)
|
|
2. Check [OpenAPI Spec](api/openapi-spec-completion.md)
|
|
3. Learn [Authentication](authentication/auth-quick-reference.md)
|
|
4. Review endpoint-specific guides (e.g., [Actions](api/api-actions.md))
|
|
|
|
### By Topic
|
|
|
|
| Topic | Primary Location | Key Files |
|
|
|-------|-----------------|-----------|
|
|
| Authentication | `authentication/` | `authentication.md`, `auth-quick-reference.md` |
|
|
| Workflows | `workflows/` | `workflow-execution-engine.md`, `workflow-orchestration.md` |
|
|
| Sensors | `sensors/` | `sensor-interface.md`, `sensor-lifecycle-management.md` |
|
|
| Testing | `testing/` | `running-tests.md`, `schema-per-test.md` |
|
|
| Performance | `performance/` | `QUICKREF-performance-optimization.md` |
|
|
| Configuration | `configuration/` | `configuration.md`, `config-troubleshooting.md` |
|
|
| CLI | `cli/` | `cli.md`, `cli-profiles.md` |
|
|
|
|
## 🔎 Search Tips
|
|
|
|
**Search by content:**
|
|
```bash
|
|
# Find all docs mentioning "execution"
|
|
grep -r "execution" docs/
|
|
|
|
# Search within a specific area
|
|
grep -r "webhook" docs/webhooks/
|
|
```
|
|
|
|
**Search by filename:**
|
|
```bash
|
|
# Find all architecture docs
|
|
find docs/architecture/ -name "*.md"
|
|
|
|
# Find testing guides
|
|
find docs/testing/ -name "*.md"
|
|
```
|
|
|
|
**Use the AGENTS.md index:**
|
|
```bash
|
|
# View minified documentation index
|
|
cat AGENTS.md
|
|
|
|
# Regenerate after adding new docs
|
|
make generate-agents-index
|
|
```
|
|
|
|
## 📖 Documentation Conventions
|
|
|
|
### File Naming
|
|
- Use lowercase with hyphens: `my-feature-guide.md`
|
|
- Prefix with category when helpful: `api-actions.md`, `testing-authentication.md`
|
|
- Use descriptive names: `workflow-execution-engine.md` not `wf-exec.md`
|
|
|
|
### Content Structure
|
|
Most documentation files follow this structure:
|
|
1. **Overview** - What this document covers
|
|
2. **Key Concepts** - Important terminology and concepts
|
|
3. **How-To** - Step-by-step instructions
|
|
4. **Examples** - Code/config examples
|
|
5. **Troubleshooting** - Common issues and solutions
|
|
6. **References** - Links to related docs
|
|
|
|
### Cross-Referencing
|
|
Use relative links to reference other docs:
|
|
```markdown
|
|
See [Authentication Guide](../authentication/authentication.md) for details.
|
|
```
|
|
|
|
## 🤝 Contributing Documentation
|
|
|
|
### Adding New Docs
|
|
1. Choose the appropriate subdirectory
|
|
2. Follow naming conventions
|
|
3. Include frontmatter if using a doc generator
|
|
4. Add cross-references to related docs
|
|
5. Run `make generate-agents-index` to update the index
|
|
|
|
### Updating Existing Docs
|
|
1. Keep the overall structure intact
|
|
2. Add new sections at the end if needed
|
|
3. Update the table of contents if present
|
|
4. Check for broken links
|
|
|
|
### Work Summaries
|
|
Daily work and session notes go in `work-summary/`, not here:
|
|
- `work-summary/sessions/` - Daily work logs
|
|
- `work-summary/status/` - Status updates
|
|
- `work-summary/phases/` - Phase completion summaries
|
|
|
|
## 🔗 External Resources
|
|
|
|
- **GitHub Repository**: [attune](https://github.com/yourusername/attune)
|
|
- **Issue Tracker**: GitHub Issues
|
|
- **Discussions**: GitHub Discussions
|
|
|
|
## 📝 Documentation Organization
|
|
|
|
For details on the documentation organization system, see [Documentation Organization](development/documentation-organization.md).
|
|
|
|
This explains:
|
|
- Why each directory exists
|
|
- What belongs where
|
|
- How to maintain the structure
|
|
- Reorganization history
|
|
|
|
## 💡 Tips
|
|
|
|
- **Start broad, go deep**: Begin with guides and overviews, then dive into specific topics
|
|
- **Check examples**: The `examples/` directory has working configurations
|
|
- **Use grep**: Full-text search is your friend for finding specific topics
|
|
- **Update AGENTS.md**: After adding docs, regenerate with `make generate-agents-index`
|
|
|
|
---
|
|
|
|
*Last updated: 2026-01-30*
|
|
*Documentation files: 100+*
|
|
*Categories: 16* |