File size: 6,240 Bytes
fbb917f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
# 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 |