Files
DataStack/docs/MANIFEST.md
T
Team Dark Devil 4279da45bb chore: establish cross-IDE synchronization protocol
Implement `.ai-rules`, formalize `MEMORY.md` as the source of truth, and initialize `docs/` structure to ensure consistent architectural context across development environments.
2026-11-18 07:11:11 +06:00

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), update docs/users/features.md.
  • Installation / Deployment Changes: Whenever modifying docker/docker-compose.yml, Dockerfiles, Nginx configurations, or .env.example, update docs/users/installation.md.
  • API Endpoints & Integration: If new parameters are added to POST /api/events or GET /api/export, update docs/users/tutorials.md and docs/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.md and docs/dev/build.md.
  • Contribution Standards: If code standards, linting rules, or multi-IDE memory rules are revised, update docs/dev/contributing.md and sync with AGENTS.md and .ai-rules.

Quality & Style Standards

  1. Markdown Formatting: Use clean GitHub-Flavored Markdown (GFM) with clear headings, bulleted lists, and language-tagged code blocks (e.g. ```bash, ```python).
  2. Absolute vs Relative Links: Inside markdown files, use relative links to reference other documentation files (e.g., [Architecture Overview](../dev/architecture.md)).
  3. No Stale Placeholders: Avoid unverified configuration keys or generic placeholder URLs; align variables with .env.example.
  4. Cross-IDE Sync: After any documentation update, update MEMORY.md in the root directory to maintain synchronization across all IDEs.