Spaces:
Sleeping
Sleeping
|
Download docs/CONTRIBUTING.md from Coeinterns/bank-statement-api: direct link, hf CLI and curl.
- Browser
- Download file 6.89 kB
-
https://huggingface.co/spaces/Coeinterns/bank-statement-api/resolve/main/docs/CONTRIBUTING.md
- Command line
-
hf download hf://spaces/Coeinterns/bank-statement-api/docs/CONTRIBUTING.md
-
curl -L -o CONTRIBUTING.md https://huggingface.co/spaces/Coeinterns/bank-statement-api/resolve/main/docs/CONTRIBUTING.md
6.89 kB
BeFree Developer Contribution Guide
This guide is designed to onboard new developers and interns onto the BeFree Bank Statement Processor project, detailing environment setups, codebase architecture tours, feature development patterns, and type checking.
1. Local Developer Setup
Follow these steps to configure your environment and run BeFree locally.
1.1 Prerequisites
- Python 3.11+ installed.
- Node.js 18+ and npm installed.
- Git installed.
- Sibling Repositories: The internal editable packages (
bank-extractorandbank-hitl) must be cloned in directories alongside this repository.
1.2 Copy Environment Configuration
cp .env.example .env
Open .env and fill in:
GOOGLE_API_KEY: Get a Gemini developer key from Google AI Studio.DATABASE_URL: Setup a free tier PostgreSQL database on NeonDB and input the URL (ensure?sslmode=requireis appended).
1.3 Setup Python Virtual Environment
# Create virtual environment
python3 -m venv venv
# Activate virtual environment
source venv/bin/activate
# Install requirements (which installs local packages in editable mode)
pip install -r requirements.txt
1.4 Database Migrations & Seeding
# Run schema migrations
python auth/migrations.py
# Seed default employee users
python auth/seed_users.py
1.5 Run Backend
python api_server.py
# The backend will start on http://localhost:8000
# OpenAPI interactive Swagger docs are available at http://localhost:8000/docs
1.6 Run Frontend
cd befree-frontend
npm install
npm run dev
# The frontend will start on http://localhost:3000
1.7 Run Both Simultaneously
Alternatively, launch both backend and frontend servers with one command:
./run.sh
2. Project Layout Tour
- api_server.py β The API server entry point that instantiates the FastAPI app, configures CORS/middlewares, and mounts the feature-domain sub-routers.
- models/ β Pydantic request/response payload schemas grouped by domain (e.g.,
statements.py,transactions.py). - core/ β Core business logic, pipeline initialization, statement IO, and global HTTP middlewares.
- routers/ β Modular FastAPI APIRouter endpoints split by feature domain (e.g.,
upload.py,dashboard.py). - auth/ β Database schemas and services for user session validation, JWT logic, and classification rules storage.
- overwatch/ β Observable stage log database store, event definitions, and context managers.
- shared/ β Shared Pydantic data schemas and constants.
- bank-classifier/ β Sequential 3-stage classification engine logic, Gemini connections, and rule promotion learners.
- befree-frontend/ β Next.js 15 frontend application.
befree-frontend/app/β Routing structure (pages).befree-frontend/features/β Feature UI components (e.g.overwatch,dashboard,coordinate-editor).befree-frontend/services/api-client.tsβ Central Axios API caller class.
- scripts/ β Diagnostic, data migration, and comparative verification utility scripts.
- data/ β Local runtime file folders (uploads, output, logs) ignored by git.
3. Adding a New API Endpoint
Backend routes are modularized inside the routers/ directory using FastAPI APIRouter objects. To declare a new route:
- Locate the appropriate router file in
routers/(e.g.,routers/review.pyorrouters/transactions.py). - Add a route using the
@routerdecorator, specifying request/response validation models frommodels/and authentication dependencies:@router.post("/new-feature", response_model=MyResponseModel) async def handle_new_feature( payload: MyRequestPayload, current_user: User = Depends(get_current_user) # Enforces JWT validation ): # Ensure roles are verified if admin-only: # if current_user.role != "admin": # raise HTTPException(status_code=403, detail="Admin only") # Business logic here return {"status": "success"} - If creating a new router file, define the
router = APIRouter(...)and mount it inapi_server.pyusingapp.include_router(new_router).
4. Adding a New Classification Rule
New classification rules can be added in two ways:
- Admin Interface: Log in as an admin role, navigate to the Rules settings dashboard, and add keywords. This calls
POST /api/v1/admin/rules. - Database Rules Seeding: To add standard rules into the system database:
- Open
bank-classifier/bank_classifier/rules/default_rules.yaml. - Add your category keyword configuration.
- Execute
python scripts/migrate_rules_to_db.pyto idempotently upsert the definitions.
- Open
5. Adding a New Frontend Feature
The frontend organizes code by features inside befree-frontend/features/.
- Component Design: Place your components inside
befree-frontend/features/my-feature/. - API Client Integration: Declare backend fetch calls in
befree-frontend/services/api-client.tsas client methods. - Zustand Store / Custom Hooks: Create local stores or query hooks inside
befree-frontend/hooks/to retrieve data. - App View: Include the feature component in a route inside
befree-frontend/app/.
6. Running the Classification Pipeline Standalone
You can invoke the classification pipeline directly from a Python script without booting the FastAPI web server:
from dotenv import load_dotenv
load_dotenv()
from bank_classifier.pipeline import ClassificationPipeline
from shared.models import NormTransaction
# Initialize pipeline
pipeline = ClassificationPipeline()
# Prepare mock transaction
tx = NormTransaction(
page_num=1,
row_num=1,
date_raw="24/05/2026",
desc_raw="Netflix subscription",
debit_raw="18.99",
amount=-18.99
)
# Run classification batch
results = pipeline.classify_batch([tx])
print(results[0].category) # Output: Recreation & Entertainment
7. Linting and Type Checking
- Frontend (TypeScript): Run static TypeScript compiler checks before submitting code:
cd befree-frontend npm run type-check - Backend (Python): The project currently does not package standard linters. It is highly recommended to install
rufffor code linting and formatting:pip install ruff # Lint code ruff check . # Format code ruff format .