Dominion/README.md

# Commercial Banking Balance Sheet & Financial Reporting Portal

A full-stack enterprise web application built for multi-branch balance sheet consolidation, trial balance ledger verification, automated accounting reconciliation, double-entry bookkeeping, and executive financial reporting.

---

## 🚀 Key Features

- **Multi-Branch Operations**: Head Office Admin, Branch Users, Maker-Checker authorization matrix.
- **Server-Side Architecture**: Express backend (`server.ts`) handling state management, calculations, audit logging, and email dispatches.
- **PostgreSQL & Fallback Storage**: Connects to PostgreSQL via `pg` connection pool with automatic fallback to JSON data persistence (`/app/data/portal-data.json`).
- **Containerized Deployment**: Ready for Docker, Docker Compose, and **Coolify** self-hosting.

---

## 📁 Repository Structure & Key Configuration Files

| File | Description |
| :--- | :--- |
| `Dockerfile` & `dockerfile` | Multi-stage production container build (Vite client + Express CJS server). |
| `docker-compose.yml` | Full-stack orchestration (App container mapped to host port 7000 + PostgreSQL container mapped to host port 7001). |
| `.dockerignore` | Defines context exclusions for slim Docker image builds. |
| `.env.example` | Template environment variables (`DATABASE_URL`, `PORT`, `HOST_PORT`, `POSTGRES_HOST_PORT`, `DATA_PATH`, `SMTP_*`). |
| `COOLIFY.md` | Complete deployment guide for Coolify platform & managed databases. |
| `server.ts` | Express server entry point with PostgreSQL initialization, environment SMTP dispatching, and REST API routes. |

---

## 🛠️ Local Development & Running via Docker

### 1. Run via Docker Compose (With PostgreSQL & Non-Conflicting Host Ports)
```bash
docker-compose up --build -d
```
By default, the application will be accessible on host port `http://localhost:7000` (mapped to internal container port `3000`), and PostgreSQL on host port `7001` (mapped to internal container port `5432`), preventing conflicts with common host ports like 3000, 8080, or 5432.

If you wish to use different custom host ports, set them in `.env`:
```env
HOST_PORT=7000
POSTGRES_HOST_PORT=7001
```

### 2. Run via Docker CLI
```bash
docker build -t balance-sheet-portal .
docker run -p 7000:3000 -v portal_data:/app/data balance-sheet-portal
```

### 3. Native Node.js Development
```bash
# Install dependencies
npm install

# Start development server (Express + Vite hot reload)
npm run dev
```

---

## ☁️ Deployment on Coolify

Refer to [`COOLIFY.md`](./COOLIFY.md) for step-by-step instructions on deploying via Docker Compose or Coolify Managed PostgreSQL.