{"id":51771969,"url":"https://github.com/mirotvoretts/alfa-copilot","last_synced_at":"2026-07-20T02:30:38.101Z","repository":{"id":371615145,"uuid":"1302019790","full_name":"mirotvoretts/alfa-copilot","owner":"mirotvoretts","description":"AI advisor for young entrepreneurs: It predicts cash flow gaps 2-3 weeks in advance and offers specific support through the bank’s products","archived":false,"fork":false,"pushed_at":"2026-07-15T21:39:17.000Z","size":1615,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-15T23:23:49.146Z","etag":null,"topics":["ai","cpp","fintech","microservices","rust"],"latest_commit_sha":null,"homepage":"","language":"Just","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mirotvoretts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-15T20:37:31.000Z","updated_at":"2026-07-15T21:40:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mirotvoretts/alfa-copilot","commit_stats":null,"previous_names":["mirotvoretts/alfa-copilot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mirotvoretts/alfa-copilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirotvoretts%2Falfa-copilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirotvoretts%2Falfa-copilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirotvoretts%2Falfa-copilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirotvoretts%2Falfa-copilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mirotvoretts","download_url":"https://codeload.github.com/mirotvoretts/alfa-copilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirotvoretts%2Falfa-copilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35671346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cpp","fintech","microservices","rust"],"created_at":"2026-07-20T02:30:37.331Z","updated_at":"2026-07-20T02:30:38.093Z","avatar_url":"https://github.com/mirotvoretts.png","language":"Just","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/banner.png\" alt=\"АльфаКопилот | AlfaCopilot\" width=\"100%\" /\u003e\n\n# АльфаКопилот | AlfaCopilot\n\n**AI-советник, который замечает кассовый разрыв за 2-3 недели до того, как он случится.**\n**An AI advisor that spots a cash-flow gap 2-3 weeks before it happens.**\n\n![status](https://img.shields.io/badge/status-prototype-EF3124?style=flat-square)\n![Alfa Future](https://img.shields.io/badge/Alfa%20Future-2026-EF3124?style=flat-square)\n![License](https://img.shields.io/badge/license-MIT-black?style=flat-square)\n\n![Rust](https://img.shields.io/badge/Rust-000000?style=flat-square\u0026logo=rust\u0026logoColor=white)\n![C++](https://img.shields.io/badge/C%2B%2B-00599C?style=flat-square\u0026logo=cplusplus\u0026logoColor=white)\n![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white)\n![React](https://img.shields.io/badge/React-20232A?style=flat-square\u0026logo=react\u0026logoColor=61DAFB)\n![gRPC](https://img.shields.io/badge/gRPC-244C5A?style=flat-square\u0026logo=google\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white)\n\n### **[Русский](#-русская-версия)  |  [English](#-english-version)**\n\n\u003c/div\u003e\n\n---\n\n## \u003ca id=\"-русская-версия\"\u003e\u003c/a\u003e Русская версия\n\n\u003e Читать на другом языке: **[English](#-english-version)**\n\n### Оглавление\n- [Проблема](#проблема)\n- [Инсайт](#инсайт)\n- [Решение](#решение)\n- [Как это работает](#как-это-работает)\n- [Демо-сценарий: Марина](#демо-сценарий-марина)\n- [Почему это сильное решение](#почему-это-сильное-решение)\n- [Архитектура](#архитектура)\n- [Технологический стек](#технологический-стек)\n- [Быстрый старт](#быстрый-старт)\n- [Структура проекта](#структура-проекта)\n- [Разработка](#разработка)\n- [Эффект для банка](#эффект-для-банка)\n\n### Проблема\n\nПлатежный бизнес Альфа-Банка охватывает молодых предпринимателей 17-25 лет недостаточно:\nсредний возраст действующего клиента - 42 года. Значимая причина потери клиентов в этом\nсегменте - не переход к конкуренту, а закрытие бизнеса. А главная причина закрытия -\nнехватка знаний и опыта, а не денег. Обычный банк замечает проблему клиента только тогда,\nкогда баланс уже ушел в минус - то есть слишком поздно.\n\n### Инсайт\n\nБанк должен входить в жизнь предпринимателя с первой продажи, а не когда у него уже есть\nоборот. Данные эквайринга появляются у банка раньше, чем проблема становится очевидной\nсамому предпринимателю. Значит, банк может предупредить, а не констатировать.\n\n### Решение\n\n**АльфаКопилот** - AI-советник внутри сервиса \"АльфаЗапуск\". Он читает реальные данные\nэквайринга, за 2-3 недели до кассового разрыва предупреждает о нем и предлагает конкретную\nподдержку через продукты Платежного бизнеса: рассрочку \"Подели\" на оборудование, сервис\nчаевых \"Нет монет\" для допдохода, гибкие тарифы эквайринга.\n\nЭто не отчет и не дашборд с цифрами. Это проактивное человеческое сообщение с планом\nдействий - то, что предприниматель реально увидит в приложении.\n\n### Как это работает\n\nПять последовательных шагов AI-цепочки. Каждый шаг появляется на экране по мере готовности -\nжюри и пользователь видят работающий пайплайн, а не готовую картинку.\n\n1. **Диагностика** - метрики из сырых транзакций: средний чек, частота операций, тренд по\n   неделям, буфер налички в днях. Считает детерминированный движок на C++.\n2. **Прогноз кассового разрыва** - через сколько дней баланс уйдет в критическую зону, с\n   уровнем уверенности.\n3. **Классификация риска** - статус зеленый / желтый / красный с обоснованием.\n4. **Рекомендация** - 2-3 конкретных действия, привязанных к продуктам банка, а не общие\n   советы вроде \"снизьте расходы\".\n5. **Проактивное сообщение** - финальный текст от лица АльфаКопилота с одним призывом к\n   действию.\n\n### Демо-сценарий: Марина\n\nМарина, 22 года, мастер маникюра из Казани, самозанятая. Принимает оплату через mPOS и\nQR-СБП. Первые два месяца доход растет. На третьем - сезонный спад и крупный разовый расход\nна оборудование. Баланс приближается к критическому уровню, но еще не отрицательный.\n\nОбычный банк заметил бы проблему по факту. АльфаКопилот замечает тревожный тренд раньше и\nпредлагает: перевести часть расходов на \"Подели\", включить \"Нет монет\" для допдохода с\nчаевых, запустить короткую акцию на провальные дни недели.\n\n### Почему это сильное решение\n\n- **Проактивность, а не констатация.** Предупреждаем за 2-3 недели, а не показываем минус\n  по факту.\n- **Реальный пайплайн, а не мокап.** Четыре микросервиса, gRPC между ними, стриминг в\n  браузер. Техническая глубина видна на защите.\n- **Привязка к продуктам банка.** Каждая рекомендация ведет в конкретный продукт Платежного\n  бизнеса - решение работает на выручку, а не только на лояльность.\n- **Работа на удержание.** Бьем в настоящую причину оттока - закрытие бизнеса из-за нехватки\n  знаний, - а не боремся за переток между банками.\n- **Детерминированность.** Фиксированный seed данных и mock-провайдер LLM: демо повторяемо и\n  запускается без единого платного ключа.\n- **Осмысленный ИИ.** ИИ встроен в путь предпринимателя и решает конкретную боль, а не\n  добавлен ради галочки.\n\n### Архитектура\n\nЧетыре сервиса, каждый на своем языке по делу. Внутри - gRPC, наружу к браузеру - WebSocket\nили SSE. Контракты (protobuf) заморожены в общей папке `proto/` и разрабатываются параллельно\nпротив моков.\n\n```mermaid\nflowchart LR\n    UI[\"Frontend | React/TS\u003cbr/\u003eдашборд + чат-лента\"]\n    GW[\"Gateway / BFF | Rust\u003cbr/\u003eAxum, WS/SSE, агрегация\"]\n    AI[\"AI Orchestrator | Python\u003cbr/\u003eцепочка промптов, стриминг\"]\n    FE[\"Financial Engine | C++\u003cbr/\u003eдетерминированная математика\"]\n    LLM[\"LLM Provider\u003cbr/\u003emock по умолчанию\"]\n\n    UI -- \"WS / SSE\" --\u003e GW\n    GW -- \"gRPC\" --\u003e AI\n    GW -- \"gRPC\" --\u003e FE\n    AI -- \"gRPC\" --\u003e FE\n    AI -- \"swappable\" --\u003e LLM\n```\n\n| Сервис | Язык | Роль |\n|---|---|---|\n| Financial Engine | C++ | Детерминированная диагностика и числовой прогноз по транзакциям. |\n| AI Orchestrator | Python | Владеет цепочкой промптов, вызывает LLM через сменный провайдер, стримит шаги. |\n| Gateway / BFF | Rust | Единая точка входа, агрегирует gRPC, отдает WS/SSE, health-checks. |\n| Frontend | React/TS | Дашборд баланса и чат-лента АльфаКопилота. |\n\n### Технологический стек\n\n- **Frontend:** React, TypeScript, Vite, архитектура Feature-Sliced Design (импорт только\n  вниз, см. `docs/frontend.md`).\n- **Gateway:** Rust, Axum/Actix, gRPC, WebSocket/SSE.\n- **AI Orchestrator:** Python, gRPC, сменный `LlmProvider` (mock / OpenAI-совместимый /\n  Ollama / Anthropic).\n- **Financial Engine:** C++20, детерминированная математика, gRPC.\n- **Инфраструктура:** Docker Compose, общие protobuf-контракты, `justfile`, GitHub Actions.\n\n### Быстрый старт\n\n```bash\ngit clone \u003crepo-url\u003e\ncd alfa-copilot\ncp .env.example .env\ndocker compose up\n```\n\nПо умолчанию `LLM_PROVIDER=mock` - демо работает без платного API-ключа и дает одинаковый\nрезультат при каждом запуске. Чтобы подключить реальный LLM, задайте `LLM_PROVIDER` и ключ\nв `.env`.\n\nФронтенд поднимется на `http://localhost:5173`, шлюз - на `http://localhost:8080`.\n\n### Онлайн-демо (GitHub Pages)\n\nСтатическая версия демо живет на `https://\u003cowner\u003e.github.io/alfa-copilot/`. Пайплайн в ней\nвыполняется прямо в браузере: те же детерминированные данные и mock-LLM, что и в полном\nстеке, поэтому результат идентичен при каждом запуске.\n\nДеплой автоматический: workflow `deploy-pages.yml` собирает фронтенд и публикует его при\nкаждом пуше в `main`. Единственная разовая настройка в репозитории: **Settings → Pages →\nBuild and deployment → Source: GitHub Actions**.\n\n### Структура проекта\n\n```\nproto/                      общие gRPC-контракты (единый источник правды)\nservices/financial-engine/  C++: диагностика и прогноз\nservices/ai-orchestrator/   Python: цепочка промптов, провайдеры LLM\nservices/gateway/           Rust: BFF, WS/SSE\nfrontend/                   React/TS: дашборд и чат (Feature-Sliced Design)\ndocs/                       контекст кейса, ТЗ, документация фронтенда\n```\n\n### Разработка\n\nВсе проверки собраны в `justfile` в двух режимах.\n\n```bash\njust hooks     # один раз после клона: включить общий pre-commit хук\njust fmt       # отформатировать все языки\njust check     # быстрый прекоммит-гейт: формат + линтеры, без тестов\njust ci        # жесткий гейт: строгие линтеры + типы + все тесты\n```\n\nПравила: максимальная строгость (ноль варнингов), запрет комментариев в коде, говорящие\nимена, строгая типизация, разработка через тесты (TDD). Полный свод - в `CLAUDE.md`.\n\n### Эффект для банка\n\n- **Раннее привлечение.** Банк полезен с первой продажи, а не после выхода на оборот.\n- **Удержание.** Прямая работа с настоящей причиной оттока - закрытием бизнеса.\n- **Рост выручки.** Рекомендации ведут в конкретные продукты Платежного бизнеса.\n- **Долгосрочная позиция.** Банк становится партнером растущего бизнеса, а не разовым\n  инструментом.\n\n---\n\n## \u003ca id=\"-english-version\"\u003e\u003c/a\u003e English version\n\n\u003e Read in another language: **[Русский](#-русская-версия)**\n\n### Table of contents\n- [The problem](#the-problem)\n- [The insight](#the-insight)\n- [The solution](#the-solution)\n- [How it works](#how-it-works)\n- [Demo scenario: Marina](#demo-scenario-marina)\n- [Why this is a strong solution](#why-this-is-a-strong-solution)\n- [Architecture](#architecture)\n- [Tech stack](#tech-stack)\n- [Quick start](#quick-start)\n- [Project structure](#project-structure)\n- [Development](#development)\n- [Impact for the bank](#impact-for-the-bank)\n\n### The problem\n\nAlfa-Bank's Payment business under-serves young entrepreneurs aged 17-25: the average active\nclient is 42. A major cause of churn in this segment is not switching to a competitor but the\nbusiness closing down. And the main reason businesses close is a lack of knowledge and\nexperience, not money. A regular bank notices the problem only once the balance is already\nnegative - too late.\n\n### The insight\n\nThe bank should enter the entrepreneur's journey at the first sale, not once there is\nturnover. Acquiring data reaches the bank earlier than the problem becomes obvious to the\nentrepreneur. So the bank can warn, not just report.\n\n### The solution\n\n**AlfaCopilot** is an AI advisor inside the \"AlfaLaunch\" service. It reads real acquiring\ndata, warns about a cash-flow gap 2-3 weeks ahead, and offers concrete support through\nPayment-business products: \"Podeli\" installments for equipment, the \"Net Monet\" tipping\nservice for extra income, flexible acquiring rates.\n\nIt is not a report or a dashboard of numbers. It is a proactive, human message with a plan of\naction - what the entrepreneur actually sees in the app.\n\n### How it works\n\nA chain of five sequential AI steps. Each step appears on screen as it completes - the judges\nand the user see a working pipeline, not a finished picture.\n\n1. **Diagnostics** - metrics from raw transactions: average check, operation frequency, weekly\n   trend, cash buffer in days. Computed by a deterministic C++ engine.\n2. **Cash-gap forecast** - how many days until the balance enters the critical zone, with a\n   confidence level.\n3. **Risk classification** - green / yellow / red status with a one-sentence rationale.\n4. **Recommendation** - 2-3 concrete actions tied to bank products, not generic advice like\n   \"cut your costs\".\n5. **Proactive message** - a final message from AlfaCopilot with a single call to action.\n\n### Demo scenario: Marina\n\nMarina, 22, a nail artist from Kazan, self-employed. She takes payments via mPOS and QR-SBP.\nIncome grows for the first two months. In the third comes a seasonal dip plus a large one-off\nequipment purchase. The balance approaches a critical level but is not yet negative.\n\nA regular bank would notice the problem after the fact. AlfaCopilot spots the worrying trend\nearlier and proposes: move part of the spend to \"Podeli\", switch on \"Net Monet\" for extra tip\nincome, run a short promo on weak weekdays.\n\n### Why this is a strong solution\n\n- **Proactive, not reactive.** We warn 2-3 weeks ahead instead of showing a negative balance\n  after the fact.\n- **A real pipeline, not a mockup.** Four microservices, gRPC between them, streaming to the\n  browser. The technical depth is visible in the defense.\n- **Tied to bank products.** Every recommendation leads into a specific Payment-business\n  product - the solution works on revenue, not only loyalty.\n- **Built for retention.** It targets the real cause of churn - businesses closing from a lack\n  of knowledge - rather than fighting over customers between banks.\n- **Deterministic.** A fixed data seed and a mock LLM provider make the demo reproducible and\n  runnable without a single paid key.\n- **Meaningful AI.** The AI is embedded in the entrepreneur's journey and solves a concrete\n  pain, not bolted on for show.\n\n### Architecture\n\nFour services, each in the language that fits its job. gRPC internally, WebSocket or SSE out\nto the browser. The protobuf contracts are frozen in a shared `proto/` directory and developed\nin parallel against mocks.\n\n```mermaid\nflowchart LR\n    UI[\"Frontend | React/TS\u003cbr/\u003edashboard + chat feed\"]\n    GW[\"Gateway / BFF | Rust\u003cbr/\u003eAxum, WS/SSE, aggregation\"]\n    AI[\"AI Orchestrator | Python\u003cbr/\u003eprompt chain, streaming\"]\n    FE[\"Financial Engine | C++\u003cbr/\u003edeterministic math\"]\n    LLM[\"LLM Provider\u003cbr/\u003emock by default\"]\n\n    UI -- \"WS / SSE\" --\u003e GW\n    GW -- \"gRPC\" --\u003e AI\n    GW -- \"gRPC\" --\u003e FE\n    AI -- \"gRPC\" --\u003e FE\n    AI -- \"swappable\" --\u003e LLM\n```\n\n| Service | Language | Role |\n|---|---|---|\n| Financial Engine | C++ | Deterministic diagnostics and numeric forecast from transactions. |\n| AI Orchestrator | Python | Owns the prompt chain, calls an LLM via a swappable provider, streams steps. |\n| Gateway / BFF | Rust | Single entry point, aggregates gRPC, serves WS/SSE, health checks. |\n| Frontend | React/TS | Balance dashboard and the AlfaCopilot chat feed. |\n\n### Tech stack\n\n- **Frontend:** React, TypeScript, Vite, Feature-Sliced Design (imports flow down only, see\n  `docs/frontend.md`).\n- **Gateway:** Rust, Axum/Actix, gRPC, WebSocket/SSE.\n- **AI Orchestrator:** Python, gRPC, a swappable `LlmProvider` (mock / OpenAI-compatible /\n  Ollama / Anthropic).\n- **Financial Engine:** C++20, deterministic math, gRPC.\n- **Infrastructure:** Docker Compose, shared protobuf contracts, `justfile`, GitHub Actions.\n\n### Quick start\n\n```bash\ngit clone \u003crepo-url\u003e\ncd alfa-copilot\ncp .env.example .env\ndocker compose up\n```\n\nBy default `LLM_PROVIDER=mock` - the demo runs without a paid API key and returns the same\nresult on every run. To use a real LLM, set `LLM_PROVIDER` and the key in `.env`.\n\nThe frontend comes up on `http://localhost:5173`, the gateway on `http://localhost:8080`.\n\n### Live demo (GitHub Pages)\n\nA static version of the demo lives at `https://\u003cowner\u003e.github.io/alfa-copilot/`. Its pipeline\nruns right in the browser with the same deterministic data and mock LLM as the full stack, so\nevery run produces the identical result.\n\nDeployment is automatic: the `deploy-pages.yml` workflow builds the frontend and publishes it\non every push to `main`. The only one-time repository setting: **Settings → Pages → Build and\ndeployment → Source: GitHub Actions**.\n\n### Project structure\n\n```\nproto/                      shared gRPC contracts (single source of truth)\nservices/financial-engine/  C++: diagnostics and forecast\nservices/ai-orchestrator/   Python: prompt chain, LLM providers\nservices/gateway/           Rust: BFF, WS/SSE\nfrontend/                   React/TS: dashboard and chat (Feature-Sliced Design)\ndocs/                       case context, spec, frontend documentation\n```\n\n### Development\n\nAll checks live in the `justfile` in two tiers.\n\n```bash\njust hooks     # once after clone: enable the shared pre-commit hook\njust fmt       # format every language\njust check     # fast pre-commit gate: format + linters, no tests\njust ci        # hard gate: strict linters + types + all tests\n```\n\nRules: maximum strictness (zero warnings), no comments in code, speaking names, strong typing,\ntest-driven development. The full set is in `CLAUDE.md`.\n\n### Impact for the bank\n\n- **Early acquisition.** The bank is useful from the first sale, not after turnover appears.\n- **Retention.** Direct work on the real cause of churn - businesses closing.\n- **Revenue growth.** Recommendations lead into specific Payment-business products.\n- **Long-term position.** The bank becomes a partner to a growing business, not a one-off tool.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nСделано для чемпионата \"Альфа-Будущее\" 2026 | Built for the \"Alfa Future\" 2026 championship\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirotvoretts%2Falfa-copilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmirotvoretts%2Falfa-copilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirotvoretts%2Falfa-copilot/lists"}