docs: implement system architecture, API specs, deployment guide, enhance demo... (!20) · Merge Requests · ThinhNC / finwise-miniapp-be

docs: implement system architecture, API specs, deployment guide, enhance demo...

Summary

This PR establishes complete technical documentation, enhances the local development seed data with a realistic demo experience, and sets up a robust automated integration testing framework using Jest and Supertest.

Key Changes

1. Technical Documentation (`/docs`)

Architecture & ERD (docs/architecture.md): Documented the layered codebase structure (Route -> Validation -> Controller -> Service -> Repository) and created a comprehensive 14-table database Entity Relationship Diagram (ERD) using Mermaid.
API Specifications (docs/api.md): Provided access details for Swagger UI, described request/response schemas, JWT bearer authorization, and summarized key endpoints.
Deployment & Ops Guide (docs/deployment.md): Included instructions for local manual setup, secure Docker Compose containerized deployment (using healthchecks and non-root users), and PM2 cluster setups.
General Overview (README.md): Updated the root documentation to serve as a clean hub with relative links pointing to the sub-documents.

2. Enhanced Demo Seed Data (`prisma/seed.ts`)

Added seedDemoData function to automatically populate the demo account (user@finwise.local) with rich financial records (3 wallets, 20+ transactions over the past 3 months, 2 monthly budgets with spending warnings, a saving goal with contributions, notifications, and reminders) to facilitate Zalo Mini App demo showcasing.

3. Integration Testing Framework (`/tests`)

Installed and configured Jest and Supertest supporting TypeScript.
Created tests/setup.ts to isolate test runs using an in-memory cache fallback (REDIS_ENABLED=false) and mocked dependencies (like mail delivery).
Written integration tests covering the base Health Check API (tests/health.test.ts) and full Authentication lifecycles (tests/auth.test.ts).

How to Verify

All checks passed successfully locally:

Run automated tests:
```
pnpm test
```
Result: 9/9 tests passed successfully (2 suites).
Verify type-checking & compile:
```
pnpm run build
```
Result: Build completed with zero errors.
Run static analysis / Linter:
```
pnpm run lint
```
Result: ESLint passed with 0 errors (configured to ignore test files).
Test database seed execution:
```
pnpm run db:seed
```
Result: Seeding completed without syntax or constraint issues.

## Summary

### Key Changes

#### 1. Technical Documentation (`/docs`)
*   **Architecture & ERD (`docs/architecture.md`)**: Documented the layered codebase structure (`Route -> Validation -> Controller -> Service -> Repository`) and created a comprehensive 14-table database Entity Relationship Diagram (ERD) using Mermaid.
*   **API Specifications (`docs/api.md`)**: Provided access details for Swagger UI, described request/response schemas, JWT bearer authorization, and summarized key endpoints.
*   **Deployment & Ops Guide (`docs/deployment.md`)**: Included instructions for local manual setup, secure Docker Compose containerized deployment (using healthchecks and non-root users), and PM2 cluster setups.
*   **General Overview (`README.md`)**: Updated the root documentation to serve as a clean hub with relative links pointing to the sub-documents.

#### 2. Enhanced Demo Seed Data (`prisma/seed.ts`)
*   Added `seedDemoData` function to automatically populate the demo account (`user@finwise.local`) with rich financial records (3 wallets, 20+ transactions over the past 3 months, 2 monthly budgets with spending warnings, a saving goal with contributions, notifications, and reminders) to facilitate Zalo Mini App demo showcasing.

#### 3. Integration Testing Framework (`/tests`)
*   Installed and configured **Jest** and **Supertest** supporting TypeScript.
*   Created `tests/setup.ts` to isolate test runs using an in-memory cache fallback (`REDIS_ENABLED=false`) and mocked dependencies (like mail delivery).
*   Written integration tests covering the base Health Check API (`tests/health.test.ts`) and full Authentication lifecycles (`tests/auth.test.ts`).

---

## How to Verify

All checks passed successfully locally:

1.  **Run automated tests**:
    ```bash
    pnpm test
    ```
    *Result: 9/9 tests passed successfully (2 suites).*

2.  **Verify type-checking & compile**:
    ```bash
    pnpm run build
    ```
    *Result: Build completed with zero errors.*

3.  **Run static analysis / Linter**:
    ```bash
    pnpm run lint
    ```
    *Result: ESLint passed with 0 errors (configured to ignore test files).*

4.  **Test database seed execution**:
    ```bash
    pnpm run db:seed
    ```
    *Result: Seeding completed without syntax or constraint issues.*