radionica3d/docs/architecture.md

Project Architecture

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

Directory Structure

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.
• ChatManager: Handles real-time communication via WebSockets (True Chat protocol).

4. WebSocket "True Chat" Protocol

To ensure high responsiveness and stability, real-time communication is handled via WebSockets:

• Global Channel (/global): Used for system-wide notifications, unread counts, and administrative alerts.
• Order Channel (/chat): A dedicated bidirectional channel per order. Messages are sent through the socket (not just via REST), allowing for instant delivery and reducing HTTP overhead.
• Persistence: While messages are handled in real-time, the backend ensures they are persisted to the database synchronously before broadcasting.

Data Flow

graph LR
    User((User Browser)) <--> Vite[Vite Dev Server / Nginx]
    Vite <--> FastAPI[FastAPI Backend]
    FastAPI <--> SQLite[(SQLite Database)]
    FastAPI <--> WS[WebSockets / Redis]
    FastAPI <--> Telegram[Telegram Bot]
    FastAPI <--> Mail[Email Server]