Implement `.ai-rules`, formalize `MEMORY.md` as the source of truth, and initialize `docs/` structure to ensure consistent architectural context across development environments.
5.6 KiB
5.6 KiB
Documentation Manifest (docs/MANIFEST.md)
Location:
/docs/MANIFEST.md
Audience: Contributors, Maintainers, and Documentation Authors
Last Updated: 2026-11-17
1. Directory Purpose & Structure
The docs/ directory contains the complete official documentation for DataStack, structured into distinct audiences to provide clarity, depth, and ease of navigation:
docs/
├── MANIFEST.md # This document (directory index & governance)
├── users/ # End-User & Operator Documentation
│ ├── README.md # User documentation overview & quick links
│ ├── installation.md # Self-hosting, Docker, and Coolify setup guides
│ ├── features.md # Guide to /vcon/ console, client tokens, and telemetry
│ ├── tutorials.md # Step-by-step user tutorials and integration walkthroughs
│ └── faq.md # Frequently asked questions and troubleshooting
└── dev/ # Developer & Contributor Documentation
├── README.md # Developer guide overview & roadmap
├── architecture.md # Deep dive into dual-runtime architecture and storage
├── setup.md # Local development environment setup & configuration
├── build.md # Build, compilation, Docker containerization & test suites
└── contributing.md # Contribution rules, conventions, and workflow
2. Directory Breakdown
docs/users/ (End-Users, System Operators & Administrators)
Designed for non-technical users, platform administrators, and data engineers operating or integrating with a live DataStack deployment:
| File | Purpose | Key Topics Covered |
|---|---|---|
README.md |
Entry point for users | Documentation map, navigation guide, and core concepts overview. |
installation.md |
Deployment guide | Production Docker Compose, Coolify 1-click deployment, environment variables, reverse proxy setup, and persistent volume management. |
features.md |
Feature breakdown | Web console (/vcon/), client SDK tokens, real-time event simulation, daily partitioned CSV storage, streaming export, and platform settings. |
tutorials.md |
Practical guides | Step-by-step tutorials: first telemetry event, connecting Python applications, viewing live events in the console, and exporting datasets. |
faq.md |
Troubleshooting & FAQ | Common questions on data retention, token revocation, port configurations, CSV rotation, and connection diagnostics. |
docs/dev/ (Developers, Contributors & System Architects)
Designed for engineers extending the codebase, fixing bugs, writing client SDKs, or contributing to the core platform:
| File | Purpose | Key Topics Covered |
|---|---|---|
README.md |
Entry point for devs | Contributor handbook, repository layout, and code navigation. |
architecture.md |
Architectural blueprint | Dual-runtime model (Port 3000 Web vs Port 4000 Ingestion), Redis durability queue, partitioned CSV engine with cooperative locks, and PostgreSQL metadata store. |
setup.md |
Local development | Prerequisites (Node.js 22, PostgreSQL, Redis), dual-terminal development, environment secrets, and sample configurations. |
build.md |
Build & compilation | Next.js standalone compilation (npm run build), ESLint validation, Docker multi-stage builds, and running TypeScript (npx tsx --test) and Python unit test suites. |
contributing.md |
Contribution standards | Multi-IDE memory synchronization (MEMORY.md & .ai-rules), UI component governance (components/ui/), code conventions, and Pull Request checklist. |
3. Maintenance & Documentation Update Guidelines
Documentation accuracy is a core quality requirement in DataStack. Whenever modifying code or configurations, follow these update rules:
When to Update docs/users/
- New User-Facing Features: Whenever adding or altering pages in
/vcon/*(e.g., changes to export options, client token regeneration, or UI settings), updatedocs/users/features.md. - Installation / Deployment Changes: Whenever modifying
docker/docker-compose.yml, Dockerfiles, Nginx configurations, or.env.example, updatedocs/users/installation.md. - API Endpoints & Integration: If new parameters are added to
POST /api/eventsorGET /api/export, updatedocs/users/tutorials.mdanddocs/users/faq.md.
When to Update docs/dev/
- Architectural Changes: Whenever altering the communication bridge between Port 3000 and Port 4000, changing Redis queues, or altering CSV storage mechanisms, update
docs/dev/architecture.md. - New Dependencies or Scripts: Whenever adding npm dependencies, changing build targets, or adding test files, update
docs/dev/setup.mdanddocs/dev/build.md. - Contribution Standards: If code standards, linting rules, or multi-IDE memory rules are revised, update
docs/dev/contributing.mdand sync withAGENTS.mdand.ai-rules.
Quality & Style Standards
- Markdown Formatting: Use clean GitHub-Flavored Markdown (GFM) with clear headings, bulleted lists, and language-tagged code blocks (e.g.
```bash,```python). - Absolute vs Relative Links: Inside markdown files, use relative links to reference other documentation files (e.g.,
[Architecture Overview](../dev/architecture.md)). - No Stale Placeholders: Avoid unverified configuration keys or generic placeholder URLs; align variables with
.env.example. - Cross-IDE Sync: After any documentation update, update
MEMORY.mdin the root directory to maintain synchronization across all IDEs.