Skip to content
ssimchenkoPublic

About

Small-business lending workspace with PDF extraction, explainable credit scoring, and client and bank dashboards.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

51 Commits

Folders and files

Repository files navigation

AlphaHub

A small-business lending workspace that turns a financial PDF into an explainable credit decision.

React TypeScript Go FastAPI Docker

Hackathon team project · Frontend Developer: Alexander Simchenko

Original team repository

Preview

AlphaHub client application status with an approved credit offer

AlphaHub multi-step business credit application AlphaHub bank employee review with explainable scoring

About

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.

What it can do

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.

My contribution

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.

Architecture

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]
Loading

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.

Tech stack

  • 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

Demo scenarios

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.

Demo accounts

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

Run locally

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 -a

Open 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 down

The 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.

Testing

Frontend:

cd frontend
npm ci
npm test
npm run typecheck
npm run build

Backend:

cd backend
go test ./... -count=1

Data 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_scenarios

The full nginx → Go → FastAPI → PostgreSQL flow is covered by scripts/smoke_demo.py. Run it against an isolated demo database because it creates applications.

MVP limitations

  • 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.

Team

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.

About

Small-business lending workspace with PDF extraction, explainable credit scoring, and client and bank dashboards.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages