voidea/docs/PROJECT_GUIDE.md

VoIdea — Project Guide

Documentation Map

Документ	Описание	Для кого
SPECIFICATION.md	Стек, причины выбора, ключевые решения	Все, кто входит в проект
TECHNICAL.md	Архитектура, схемы, data flow	Разработчики
webui/STYLE_GUIDE.md	Код-стайл, Zustand, формы, a11y, ESLint, тесты	Frontend-разработчики
versioning.md	SemVer, CHANGELOG, agent versioning	Все
user-guide.md	Пользовательская инструкция	Пользователи
admin-guide.md	Администрирование VPS	Администраторы
docs/blocks/00-rules.md	Конституция проекта	Все
docs/design-system/README.md	Дизайн-токены + генераторы	UI/UX + разработчики

Quick Start

# Backend
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate # Linux
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8020

# Frontend
cd webui
npm install
npm run dev

VPS Deploy

# Ubuntu 22.04+
git clone <repo> /opt/voidea
cd /opt/voidea
chmod +x deploy/deploy.sh
./deploy/deploy.sh

See admin-guide.md for full VPS setup.

Architecture Principles

1. Documentation first — decisions are written down before code.
2. Purity over speed — "кривой код = переписать сразу".
3. Growth-proof — все решения принимаются с учётом будущих мобильных приложений и объединения проектов.
4. VPS-ready — весь код пишется сразу для Ubuntu + Nginx + systemd.
5. Accessibility by default — WCAG AA, enforced by CI.