# BeFree Dependency Map This document maps the relationships between the internal editable packages and catalogues the external dependencies of the BeFree Bank Statement Processor. --- ## Part A: Internal Package Dependency Graph The BeFree Monorepo contains packages that are installed in editable mode (`-e`) during setup. ``` api_server.py (FastAPI App Entry Point) ├── core/ (Core Logic & Middlewares) ├── models/ (FastAPI Pydantic Schemas) ├── routers/ # Modular Endpoint APIRouters ├── auth/ (Local Module) ├── overwatch/ (Local Module) ├── shared (Local Package: shared/) ├── bank-extractor (Local Package: bank-extractor/) [Not in this repo snapshot] ├── bank-classifier (Local Package: bank-classifier/) │ ├── shared (Dependency) │ └── auth.rule_models (Cross-Module Import Coupling - see note) └── bank-hitl (Local Package: bank-hitl/) [Not in this repo snapshot] ``` ### Dependency Notes & Coupling Warning: > [!WARNING] > **Cross-Module Coupling**: The `bank-classifier` package imports directly from `auth.rule_models` (specifically to load categories, rule definitions, and BPAY billers from PostgreSQL database tables). > This introduces a tight coupling between the classification pipeline and the authentication database schema. > > *Future Refactor Recommendation*: In a production microservices scenario, this connection should be decoupled. The classification pipeline should load rules using a repository interface or an abstract `RuleStore` service, or query rules through a secure internal HTTP REST endpoint. --- ## Part B: Sibling Package Dependencies The following packages are referenced in `requirements.txt`, `Dockerfile`, and `run.sh`, but their source code resides in separate Git repositories outside this repository's root: 1. `bank-extractor` — Installed as `-e bank-extractor` (requires directory `../bank-extractor` relative to this repo root in some workspaces, or colocated as a sibling). 2. `bank-hitl` — Installed as `-e "bank-hitl[web]"`. Exposes review interface endpoints and correction handlers. Both packages must be cloned and present alongside this project to install dependencies and run locally. --- ## Part C: Backend External Dependencies (`requirements.txt`) | Package Name | Version Pinned | Purpose | Dependency Type | | :--- | :--- | :--- | :--- | | `fastapi` | No | Core web framework for endpoint routing | Runtime | | `uvicorn[standard]`| No | ASGI server used to run the FastAPI application | Runtime | | `python-multipart`| No | Decodes multipart form-data requests during file uploads | Runtime | | `PyMuPDF` | No | Accesses, scans, and parses text/layout from PDF statements | Runtime | | `openpyxl` | No | Creates, styles, and writes the final multi-sheet Excel reports | Runtime | | `google-genai` | No | Google Gemini API SDK used for fallback classifications | Runtime | | `python-dotenv` | No | Automatically reads configurations from the local `.env` file | Runtime / Dev | | `python-jose[cryptography]` | No | Encrypts, signs, and decodes JWT security tokens | Runtime | | `passlib[bcrypt]` | No | Securely hashes passwords using the bcrypt algorithm | Runtime | | `sqlalchemy` | No | SQL Database Toolkit and Object Relational Mapper (ORM) | Runtime | | `psycopg2-binary` | No | PostgreSQL database adapter for Python | Runtime | --- ## Part D: Frontend External Dependencies (`befree-frontend/package.json`) ### Runtime Dependencies | Package Name | Version Pinned | Purpose | | :--- | :--- | :--- | | `next` | `^15.0.0` (Yes) | React web framework | | `react` | `^18.3.1` (Yes) | UI development library | | `react-dom` | `^18.3.1` (Yes) | React DOM rendering | | `@tanstack/react-query`| `^5.28.0` (Yes) | Server state management and API polling | | `@tanstack/react-table`| `^8.17.3` (Yes) | Utilities for rendering sortable/filterable tables | | `@tanstack/react-virtual`| `^3.13.24` (Yes)| Virtualization utilities for rendering large logs | | `@react-pdf-viewer/core`| `^3.12.0` (Yes) | Renders statement PDFs directly in the browser | | `@react-pdf-viewer/default-layout`| `^3.12.0` (Yes) | Layout framework for PDF viewer | | `axios` | `^1.6.2` (Yes) | HTTP client for interacting with the backend API | | `zustand` | `^4.4.1` (Yes) | Global client-side state management | | `zod` | `^3.22.4` (Yes) | Schema validation library for frontend payloads | | `@hookform/resolvers` | `^3.3.4` (Yes) | Form validation schemas using Zod | | `react-hook-form` | `^7.51.3` (Yes) | Client form collection and validation | | `framer-motion` | `^10.16.16` (Yes) | UI transitions and micro-animations | | `lucide-react` | `^0.344.0` (Yes) | Icon catalog | | `class-variance-authority` | `^0.7.0` (Yes)| Tailwind CSS component utility | | `tailwind-merge` | `^2.2.2` (Yes) | Utility to merge tailwind classes | | `clsx` | `^2.0.0` (Yes) | Constructing `className` strings conditionally | | `cmdk` | `^0.2.0` (Yes) | Command menu component | | `shadcn-ui` | `latest` (No) | Premium pre-built UI components | | `@radix-ui/react-*` | Various (Yes) | Accessible, unstyled primitive components | ### Development Dependencies | Package Name | Version Pinned | Purpose | | :--- | :--- | :--- | | `typescript` | `^5.3.3` (Yes) | TypeScript compilation and static typing | | `@types/node` | `^20.10.6` (Yes) | Node.js typing files | | `@types/react` | `^18.2.46` (Yes) | React core typing definitions | | `@types/react-dom`| `^18.2.18` (Yes) | React DOM rendering typings | | `eslint` | `^8.56.0` (Yes) | Static code analysis linter | | `eslint-config-next`| `^15.0.0` (Yes) | Next.js eslint configurations | | `@typescript-eslint/eslint-plugin`| `^6.17.0` (Yes) | TypeScript specific linting rules | | `@typescript-eslint/parser`| `^6.17.0` (Yes) | TS parser for eslint | | `tailwindcss` | `^3.4.1` (Yes) | Utility-first CSS styling framework | | `postcss` | `^8.4.32` (Yes) | CSS preprocessor | | `autoprefixer` | `^10.4.16` (Yes)| PostCSS plugin to parse CSS and add vendor prefixes |