# Wings Finance

Finance ERP scaffolding — Node.js/Express + PostgreSQL backend, React/Vite + Tailwind frontend (plain JavaScript).

## Structure

```
backend/     Express API (modular domains under src/modules/)
frontend/    React + Vite SPA (features under src/features/)
```

## Quick start

### Backend

```bash
cd backend
cp .env.example .env   # set DATABASE_URL when Postgres is ready
npm install
# optional: start Postgres via Docker
# docker compose up -d
npm run migrate        # when Postgres is up
npm run dev
```

API boots even if Postgres is down (`DB_REQUIRED=false`). Demo auth:

- `POST /api/auth/login` — `admin@wings.local` / `admin123` (or empty body for demo)
- `GET /api/auth/me` — Bearer token

Postgres via Docker:

```bash
docker compose up -d
```

### Frontend

```bash
cd frontend
cp .env.example .env
npm install
npm run dev
```

## Database (PostgreSQL)

- Connection pool: `backend/src/config/database.js`
- Transactions: `backend/src/config/db-transaction.js` → `withTransaction(async (client) => { ... })`
- Migrations: `backend/migrations/` via **node-pg-migrate** (versioned up/down)

```bash
npm run migrate              # up
npm run migrate:down         # rollback last
npm run migrate:create name  # scaffold next migration
npm run migrate:status
```

Naming convention: `001_create_audit_logs.js`, `002_create_idempotency_keys.js`, …
Put schema SQL inside `pgm.sql(\`...\`)` so changes stay reviewable and rollbackable.

## Finance cross-cutting

| Concern                             | Location                                                        |
| ----------------------------------- | --------------------------------------------------------------- |
| Audit trail (mandatory on CRUD)     | `src/shared/services/auditLog.js`                               |
| Idempotency (payments/transactions) | `src/middleware/idempotency.js` — send `Idempotency-Key` header |
| Multi-table commits                 | `src/config/db-transaction.js`                                  |

## Adding a new module

1. Copy `backend/src/modules/_template` → `backend/src/modules/<module-name>`
2. Wire the router in `backend/src/routes/index.js`
3. Copy `frontend/src/features/_template` → `frontend/src/features/<module-name>`
4. Register the route in `frontend/src/routes/index.jsx`
5. Add a numbered migration for any new tables

### Styling

Frontend uses **Tailwind CSS** with a **SmartHR-inspired** theme
(primary `#0094D1`, Roboto, 5px radius, 252px sidebar).

Design tokens: `frontend/src/assets/styles/variables.css`  
Shared UI: `frontend/src/components/ui/`
(`Button`, `Badge`, `Input`, `Select`, `Card`, `Table`, `Modal`, `Alert`,
`Pagination`, `Breadcrumb`, `PageHeader`, …)