# Project Architecture

This document describes the high-level architecture and the directory structure of the Radionica 3D project.

## Directory Structure

```text
radionica3d/
├── backend/            # FastAPI application
│   ├── .venv/          # Python virtual environment (ignored)
│   ├── migrations/     # Current SQL migrations
│   ├── routers/        # API endpoint definitions (admin, auth, orders, etc.)
│   ├── services/       # Core business logic (pricing, email, audit, fiscalization)
│   ├── tests/          # Python unit and integration tests
│   ├── uploads/        # Local storage for user files (ignored in production, use persistent volume)
│   ├── main.py         # Entry point for the FastAPI server
│   ├── database.db     # SQLite database file
│   └── requirements.txt # Python dependencies
├── src/                # Vue 3 Frontend
│   ├── assets/         # Static images and global styles
│   ├── components/     # Reusable UI components
│   ├── lib/            # API client (Axios-based) and utility functions
│   ├── locales/        # Localization JSONs and master fragments
│   ├── pages/          # Page components (routed)
│   ├── router/         # Vue Router configuration
│   ├── stores/         # Pinia state stores (auth, settings)
│   └── App.vue         # Root component
├── public/             # Static assets served by Vite directly
├── scripts/            # Build and utility scripts (localization, sitemap)
├── legacy/             # Archived migration scripts and old components (unused)
├── docs/               # This documentation
├── nginx.conf          # Production Nginx configuration
├── docker-compose.yml  # Containerization setup
└── vite.config.ts      # Vite build configuration
```

## Core Concepts

### 1. Unified Localization (i18n)
The project uses a "Source of Truth" approach for translations.
- **Fragments**: Small JSON files in `src/locales/master_user/` and `src/locales/master_admin/`.
- **Assembly**: The `scripts/manage_locales.py` script merges these fragments into `translations.user.json` and `translations.admin.json`.
- **Splitting**: The same script then splits the merged files into individual language files (e.g., `en.json`, `ru.json`) which are imported by `src/i18n.ts`.

### 2. Order Workflow
1. **User Side**: Uploads a file -> Order created as `pending` -> Chat opens.
2. **Admin Side**: Receives notification (Telegram) -> Reviews file -> Updates status/price -> Chats with user.
3. **Execution**: Printing -> Delivery via Mail -> Payment.

### 3. Service-Oriented Backend
The backend logic is decoupled into services:
- `AuditService`: Tracks all critical actions (order changes, logins) for security.
- `FiscalService`: Handles digital signing and QR code generation for invoices (Montenegro EFI).
- `PricingService`: Logic for calculating print costs based on material and weight.
- `EmailService`: Sends notifications for order status changes and password resets.

## Data Flow
```mermaid
graph LR
    User((User Browser)) <--> Vite[Vite Dev Server / Nginx]
    Vite <--> FastAPI[FastAPI Backend]
    FastAPI <--> SQLite[(SQLite Database)]
    FastAPI <--> Telegram[Telegram Bot]
    FastAPI <--> Mail[Email Server]
```