🧮 Chaos Calculator

Калькулятор, в котором правит анархия и мнение большинства

📄 Описание

Chaos Calculator — это необычный калькулятор, в котором правильность математического ответа определяется не законами логики, а мнением большинства. Это веб-приложение с асинхронным бэкендом на FastAPI и интерактивным фронтендом на React.

Здесь правильный ответ на выражение 2+2 — это тот результат, за который проголосовало больше всего пользователей. Полная математическая анархия, управляемая краудсорсингом!

📌 Скриншоты

📊 Статистика и качество

🧪 Покрытие кода тестами: 81%

🛠 Качество кода: проект проходит строгую проверку Ruff (линтинг и форматирование) и Mypy (строгая статическая типизация).

🔄 CI/CD: настроен автоматический пайплайн в GitHub Actions (main.yml). При каждом пуше или пулл-реквесте автоматически запускаются тесты, проверяется линтер и контролируется уровень покрытия кода.

🧠 Компоненты системы

Архитектура приложения разделена на независимые слои:

• API Layer (FastAPI): Обрабатывает входящие HTTP-запросы, валидирует данные с помощью Pydantic-схем и управляет сессиями БД через Dependency Injection (Depends).
• Repository Layer: Инкапсулирует в себе всю сложную работу с базой данных (атомарные UPSERT-запросы на чистом SQLAlchemy).
• Cache Service (Redis): Обеспечивает мгновенную отдачу популярных и часто запрашиваемых выражений, снижая нагрузку на реляционную базу данных.
• Database (PostgreSQL): Надежное хранилище для двух связанных таблиц (expressions и answers) с каскадным удалением и уникальными индексами.

🎯 Возможности

• 🔍 Расчет выражений: получение текущего "лидирующего" ответа для любого математического примера.
• 🧑‍🏫 Обучение калькулятора: возможность проголосовать за свой вариант ответа (или предложить новый). Счетчик голосов обновляется атомарно.
• 📈 Интерактивная статистика: отображение топ-5 самых популярных ответов для конкретного выражения (идеально для графиков на фронтенде).
• ⚡ Высокая скорость: кэширование результатов вычислений в Redis.

📋 Требования

Для запуска проекта вам понадобятся:

• Docker и Docker Compose (рекомендуемый способ)

Для локальной разработки и запуска тестов (без Docker):

• Python 3.14
• Poetry (менеджер зависимостей)
• Node.js и npm/bun (для фронтенда)

🚀 Запуск проекта

1. Клонируйте репозиторий:

   git clone https://github.com/ksredkin/chaos-calc.git
   cd chaos-calc

2. Создайте файл .env в корневом каталоге и настройте переменные окружения по примеру из .env.example.

3. Запустите всю инфраструктуру одной командой:

   docker compose up --build -d

⭐ Примечание

Если проект показался вам интересным или забавным — не забудьте поставить ⭐ на GitHub! Это мотивирует развивать анархическую математику дальше. 🚀