# 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

```bash
# 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

```bash
# 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.