# VoIdea — Technical Architecture

## System Overview

```
┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client  │────▶│  Nginx   │────▶│  FastAPI │────▶ PostgreSQL
│ (PWA/Web)│     │ :80/443  │     │ :8020    │────▶ Redis
└──────────┘     └──────────┘     └──────────┘     ┌──────────┐
                                                    │ Celery   │
                                                    │ (AI/backup)
                                                    └──────────┘
```

## Frontend (webui/) Architecture

### Layer Structure

```
pages/          ← Route-level components (1 page = 1 route)
  ├── LoginPage.tsx
  ├── IdeaEdit.tsx
  └── AdminPage.tsx
components/     ← Shared UI
  ├── Layout.tsx
  ├── ErrorBoundary.tsx
  ├── SkipToContent.tsx
  ├── VoiceChat.tsx
  └── HelpFAB.tsx
stores/         ← Zustand stores
  ├── auth.ts   (migration target from AuthContext)
  ├── ideas.ts
  └── settings.ts
api/            ← HTTP client
  ├── client.ts
  └── endpoints.ts
constants/      ← i18n-ready strings
  └── strings.ts
hooks/          ← Custom hooks
  ├── useVoiceCommands.ts
  └── useBroadcastChannel.ts
types/          ← Shared TS types
  └── index.ts
```

### Data Flow

```
User Action (click, voice)
  → Page component
    → Zustand store action (or react-hook-form submit)
      → api/client.ts (fetch with JWT)
        → FastAPI endpoint
          → Service layer
            → Database / AI
          ← Response
        ← JSON
      ← Store update (set state)
    ← React re-render (only subscribers)
  ← UI update
```

### Auth Flow

```
Login/Register
  → POST /api/v1/auth/login
  ← { access_token, refresh_token }
  → setTokens() → localStorage
  → Zustand store: user = fetched /users/me
  → apiFetch() reads token from store (not localStorage)

On page load:
  → isAuthenticated() checks localStorage
  → GET /users/me
  → 200: setUser(data)
  → 401: clearTokens(), redirect /login
```

### Error Boundary Flow

```
Error in render
  → <ErrorBoundary> catches (componentDidCatch)
  → Logs to console.error
  → Shows <ServerErrorPage /> (fallback UI)
  → User clicks "На главную"
  → navigate("/")
```

## Backend Layer

See `app/` directory structure. Key modules:
- `app/api/v1/` — REST endpoints (auth, ideas, users, admin, agents, sync)
- `app/services/` — Business logic
- `app/models/` — SQLAlchemy ORM
- `app/schemas/` — Pydantic request/response
- `app/agents/` — 11 system agents (DocAgent, QATesterAgent, etc.)
- `app/integrations/` — AI providers (YandexGPT, GigaChat), OAuth
- `app/core/` — Config, security, DB, dependencies

## Design Tokens

Source of truth: `docs/design-system/tokens.json`

Generators:
| Platform | Generator | Output |
|----------|-----------|--------|
| Web (CSS) | `generators/css_generator.py` | `app/design-tokens/css/theme.css` |
| iOS (Swift) | `generators/swift_generator.py` | `app/design-tokens/swift/Colors.swift` |
| Android (Kotlin) | `generators/kotlin_generator.py` | `app/design-tokens/kotlin/colors.xml` |

## Backups

- Cron: daily at 03:00 (server time)
- Retention: 7 days
- Output: `/opt/voidea/backups/`
- Tool: `tools/backup_db.py`