A small-business lending workspace that turns a financial PDF into an explainable credit decision.
Hackathon team project · Frontend Developer: Alexander Simchenko
AlphaHub brings the small-business credit process into one workspace. A client selects a loan, uploads a financial statement, checks the extracted figures, and submits the application. The system calculates an explainable score and routes the case to an automatic offer, manual review, or rejection.
A bank employee sees the company, source PDF, financial data, score factors, documents, and full decision history in one application card. The MVP keeps extraction failures separate from credit decisions and checks access to applications on the server.
| Business client | Bank employee |
|---|---|
| Register and manage a company profile | Search and filter the application queue |
| Compare loan products and save a draft | Review company, PDF, and financial data |
| Upload a PDF and correct extracted figures | Inspect positive and negative score factors |
| Submit an application and follow its timeline | Assign a case and request more information |
| Respond to information requests | Approve, reject, or propose different terms |
| Accept or decline an offer | Track every action in the application history |
The server enforces application ownership. Data versions prevent an outdated form from overwriting newer financial information. An extraction or scoring-service failure does not become a credit rejection.
As Frontend Developer, I worked on the client and bank interfaces and their integration with the backend:
- built the React and TypeScript application for both user roles;
- implemented the multi-step loan application, local draft recovery, validation, and PDF workflow;
- created company, product, application status, offer, bank queue, and decision screens;
- connected the UI to the Go API and replaced the initial mock data flow;
- added frontend contract tests and handled API, session, and validation errors;
- polished the integrated user journey and the explainable scoring presentation.
The repository preserves the team history and credits every contributor.
flowchart LR
UI[React + TypeScript] -->|REST / JWT| API[Go API]
API --> DB[(PostgreSQL)]
API --> Files[PDF storage]
API -->|Extraction and scoring| DS[Python / FastAPI]
DS --> Parser[pdfplumber]
DS --> Rules[financial_rules_v2]
The Python service extracts and scores the financial data. The Go service owns authentication, persistence, access control, workflow state, and the final routing decision.
Detailed references: architecture · data model · application states · API contracts.
- Frontend: React 19, TypeScript 5, Vite 8, React Router 7, Vitest
- Backend: Go, PostgreSQL, pgx, JWT
- Data service: Python, FastAPI, Pydantic, pdfplumber
- Delivery: Docker Compose, nginx, automated database migrations
- Quality: frontend contract tests, Go unit and integration tests, Python API and scoring tests
The repository includes synthetic PDFs with deterministic expected results:
| Document | Product | Amount / term | Score | Result |
|---|---|---|---|---|
stable.pdf |
Working capital loan | 2M RUB / 12 months | 83 | Automatic offer |
medium.pdf |
Working capital loan | 1M RUB / 18 months | 57 | Manual review |
risky.pdf |
Working capital loan | 5M RUB / 12 months | 16 | Rejection |
equipment.pdf |
Equipment loan | 2M RUB / 24 months | 91 | Automatic offer |
The documents cover April–September 2026 and are valid for a first submission in October 2026. They are synthetic and do not represent real companies or bank data. Expected results are covered by test_demo_scenarios.py.
All demo accounts use password AlphaHubTest2026!.
| Account | Purpose |
|---|---|
client@demo.ru |
Client for stable.pdf and equipment.pdf |
medium@demo.ru |
Client for medium.pdf |
risky@demo.ru |
Client for risky.pdf |
bank@demo.ru |
Bank employee |
Requirements: Git, Docker Engine or Docker Desktop with Linux containers, and Docker Compose v2. Windows requires WSL2.
git clone https://github.com/ssimchenko/AlphaHub.git
cd AlphaHub
docker compose up --build -d
docker compose ps -aOpen http://localhost:5173. The migrate container should exit with code 0; the remaining services should become healthy.
docker compose logs --tail=100 backend ds migrate
docker compose downThe default ports are 5173, 8080, 8001, and 5433. Copy .env.example to .env to change them. Demo secrets are local defaults and must not be used for an Internet deployment.
Frontend:
cd frontend
npm ci
npm test
npm run typecheck
npm run buildBackend:
cd backend
go test ./... -count=1Data service:
cd ds
python -m unittest test_api test_metrics test_schema_contract test_financials_api test_pdf_validation test_product_conditions test_scoring test_score_result test_risk_flags test_demo_scenariosThe full nginx → Go → FastAPI → PostgreSQL flow is covered by scripts/smoke_demo.py. Run it against an isolated demo database because it creates applications.
- The default parser handles text-based PDFs in the documented format; scanned files and arbitrary layouts require OCR or a separate Docling pipeline.
- External company, tax, and credit-bureau services are not connected.
- Signing and loan disbursement after offer acceptance are simulated.
- The score is rule-based and is not trained or calibrated on real repayment data.
- The rules-versus-ML study uses synthetic applications and does not prove real-bank performance.
AlphaHub was built by a hackathon team. This portfolio copy keeps the original authors, dates, and contributor attribution while presenting the history as a clean linear sequence.
- Alexander Simchenko — Frontend Developer
- Stanislav Gupaliuk — Backend development and integration
- Igor Maiorov — Data service and scoring
- Elena Stepnova — Scoring experiments and analysis
See the original team repository for the source collaboration history. Additional project material is available in SUBMISSION.md and THIRD_PARTY_NOTICES.md.


