bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: documenting modular architecture and testing infrastructure

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-15 16:44:15 +03:00
parent db918a86ab
commit e5963123ab
2 changed files with 11 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
PROJECT_ARCHITECTURE.md
View File

@@ -13,6 +13,7 @@ A unified system to maintain an inventory of "items" and their quantities, inclu
- **Validation:** Pydantic v2 - **Validation:** Pydantic v2
- **Auth:** Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching - **Auth:** Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching
- **AI Engine:** Google GenAI SDK (Gemini 2.0 Flash) & Anthropic SDK (Claude 3.5 Sonnet) - Location: `backend/ai/` - **AI Engine:** Google GenAI SDK (Gemini 2.0 Flash) & Anthropic SDK (Claude 3.5 Sonnet) - Location: `backend/ai/`
- **Testing:** Pytest (Unit & Integration) - Location: `backend/tests/`
### 2.2 Frontend (Web & PWA) ### 2.2 Frontend (Web & PWA)
- **Architecture:** Next.js 15+ (App Router) - **Architecture:** Next.js 15+ (App Router)
@@ -27,6 +28,7 @@ A unified system to maintain an inventory of "items" and their quantities, inclu
- **Offline persistence:** Dexie.js (IndexedDB wrapper) - **Offline persistence:** Dexie.js (IndexedDB wrapper)
- **Scanner:** `html5-qrcode` (Client-side, offline-only) - **Scanner:** `html5-qrcode` (Client-side, offline-only)
- **Sync:** Axios with bulk-sync idempotency (UUID-based) - **Sync:** Axios with bulk-sync idempotency (UUID-based)
- **Testing:** Vitest (React Hook Testing) - Location: `frontend/tests/`
### 2.3 Operations & Tooling ### 2.3 Operations & Tooling
- **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json) - **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json)
@@ -110,3 +112,5 @@ To ensure deployment stability on macOS environments with potentially broken dev
109: - **Unified AI Core:** The backend uses an abstraction layer to handle multiple AI providers (Gemini and Claude). 109: - **Unified AI Core:** The backend uses an abstraction layer to handle multiple AI providers (Gemini and Claude).
110: - **Dynamic Configuration:** System settings (AI Provider, API Keys, Backup Policies) are managed via `backend/config_manager.py`, allowing real-time updates without restarting the container. 110: - **Dynamic Configuration:** System settings (AI Provider, API Keys, Backup Policies) are managed via `backend/config_manager.py`, allowing real-time updates without restarting the container.
111: - **Admin Standardization:** The Admin Dashboard features a standardized configuration UI with secure field masking for sensitive credentials. 111: - **Admin Standardization:** The Admin Dashboard features a standardized configuration UI with secure field masking for sensitive credentials.
- **Architectural Modularization (v1.10.0):** The monolithic Admin and Inventory pages have been refactored into a modular architecture. Frontend logic is decoupled into custom React hooks (`useAdmin`), and UI is extracted into standalone components (`IdentityManager`, `DatabaseManager`, etc.). Backend admin endpoints are split into domain-specific routers (`backups`, `config`) for improved maintainability.
- **Verification Infrastructure:** A dual-layer testing suite is implemented: Pytest for backend integration (using in-memory SQLite and mocked auth) and Vitest for frontend logic validation.

7
README.md
View File

@@ -62,6 +62,13 @@ To generate a clean production package and snapshot the current state:
* **Proxy:** Caddy (Docker) or local-ssl-proxy (Standalone/Dev). * **Proxy:** Caddy (Docker) or local-ssl-proxy (Standalone/Dev).
* **AI Engine:** Google Gemini (Generative AI SDK). * **AI Engine:** Google Gemini (Generative AI SDK).
## 🧪 Testing & Verification (v1.10.0+)
The project includes a comprehensive testing suite to ensure architectural stability:
- **Backend:** `pytest` integration tests with in-memory database mocks.
- Run: `PYTHONPATH=. ./backend/venv/bin/pytest backend/tests/`
- **Frontend:** `vitest` unit tests for custom React hooks and state logic.
- Run: `npm run test` (requires Node 20+)
For more details, see [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md). For more details, see [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).
--- ---