---

🚀 Evolute DSS - Frontend Application

📖 Overview

Evolute DSS (Decision Support System) is an enterprise-grade web application designed to automate the strategic planning and optimization of software development processes based on maturity models (e.g., CMMI, SPICE).

This frontend application serves as the interactive interface for QA Engineers and Top Management, allowing them to configure complex mathematical models, manage budgets, and visualize optimal investment trajectories calculated by the backend's Dynamic Programming and Branch-and-Bound algorithms.

✨ Key Features

• 🔐 Role-Based Access Control (RBAC): Strict separation of duties between Master QA (global supervision, user management) and QA Engineer (isolated project workspaces).
• 📊 Interactive Dashboards: Real-time KPIs, donut charts for project statuses, and utility growth analytics.
• 🛠 Advanced Model Configuration: A dynamic, multi-step wizard for configuring maturity models, including category weights ($\eta$), process weights ($\gamma$), utility vectors, and transition cost matrices.
• ⚡ Real-Time Synchronization: Integration with WebSockets (STOMP) for instant UI updates during long-running mathematical calculations, eliminating the need for manual page reloads.
• 📈 Data Visualization: High-performance, interactive charts (built with Recharts) to visualize financial trajectories, global utility growth, and step-by-step process capability evolution.
• 📄 PDF Report Generation: Automated generation of strict, print-ready analytical reports (A4 format) with vector graphics and dynamic executive summaries.
• 🌍 Internationalization (i18n): Full support for English and Ukrainian languages with on-the-fly switching.

🏗 Architecture & Tech Stack

The application is built with a focus on performance, maintainability, and modern React patterns:

• Framework: React 18 with TypeScript for strict type safety.
• Bundler: Vite for lightning-fast HMR and optimized production builds.
• State Management:
  • @tanstack/react-query for server-state management, caching, and optimistic UI updates.
  • zustand for lightweight, boilerplate-free global client state (e.g., user sessions).
• Styling: Tailwind CSS v4 for utility-first styling, combined with clsx and tailwind-merge for dynamic class composition.
• UI Components: Custom-built, accessible components inspired by shadcn/ui, utilizing lucide-react for iconography.
• Data Visualization: recharts for responsive SVG charts.
• PDF Export: html2canvas and jspdf for high-quality, client-side document generation.

📂 Project Structure (Feature-Sliced Design)

The codebase follows a modular, feature-based architecture to ensure scalability:

src/
├── app/                    # App initialization (Router, Global Store)
├── components/             # Shared UI components (Layouts, Modals, Error Boundaries)
├── features/               # Isolated business features
│   ├── auth/               # Authentication, User Management, Profile Settings
│   ├── dashboard/          # Global analytics and KPIs
│   └── projects/           # Project CRUD, Model Configuration, Roadmap Visualization
│       ├── components/     # Feature-specific UI
│       ├── hooks/          # Custom hooks (e.g., useProjectConfiguration, useWebSocket)
│       └── types/          # TypeScript interfaces matching Backend DTOs
├── lib/                    # Utilities (Axios instance, Tailwind cn, i18n setup)
└── locales/                # JSON translation dictionaries (en, uk)

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone the repository:

   git clone <repository-url>
   cd evolute-frontend

2. Install dependencies:

   npm install

3. Configure Environment Variables: Ensure the backend API URL is correctly set in src/lib/api.ts (default is http://localhost:8080/api).

4. Start the development server:

   npm run dev

   The application will be available at http://localhost:5173.

Building for Production

To create an optimized production build:

npm run build

The compiled assets will be generated in the dist/ directory, ready to be served by Nginx or any static file hosting.

🛡 Security Considerations

• Stateless Authentication: The frontend does not store JWT tokens in localStorage or memory. It relies entirely on HttpOnly cookies managed by the browser, providing robust protection against Cross-Site Scripting (XSS) attacks.
• Optimistic UI Locks: The interface automatically disables inputs and action buttons when a project enters the CALCULATING state, preventing race conditions and data corruption.

👨‍💻 Development Guidelines

• Code Formatting: The project uses Prettier and ESLint. Run npm run format before committing to ensure Tailwind classes are properly sorted and code style is consistent.
• Translations: When adding new text to the UI, always use the useTranslation hook and update both en/translation.json and uk/translation.json.

---