# NexusCRM

![Status](https://img.shields.io/badge/Status-Strict_Verified-green)
![Architecture](https://img.shields.io/badge/Architecture-Clean_%26_Hexagonal-blue)
![SSoT](https://img.shields.io/badge/SSoT-CodeGen_Enforced-purple)

**NexusCRM** is a metadata-driven CRM platform built for scale, reliability, and observability. It features a strict **Clean Architecture** backend and a **Single Source of Truth (SSoT)** code generation pipeline.

## 🚀 Key Features

- **Metadata-Driven**: Schema, UI, and Business Logic are stored as data. Modification requires NO code deployment.
- **Strict Architecture**: separation of concerns via Go Hexagonal Architecture.
- **Golden Thread Observability**: tracing via `X-Request-ID` from UI click to DB query.

## 📚 Documentation

- **[System Architecture](./docs/ARCHITECTURE.md)** (MUST READ) - Detailed breakdown of layers, pillars, and patterns.
- **[Security Model](./docs/SECURITY.md)** - Permissions, Profiles, and Field-Level Security.
- **[User Manual](./docs/USER_MANUAL.md)** - Guide for end-users.
- **[Control Plane Setup Apply](./docs/guides/control-plane-setup-apply.md)** - Local setup/verify workflow for read-only server startup.
- **[Test Infra](./docs/test-infra/README.md)** - Regression strategy, issue-to-test policy, and current API/UI backlog docs.

## 🛠 Project Structure

```bash
/
├── backend/                   # Go Clean Architecture
│   ├── cmd/                   # Entry points (server, codegen)
│   ├── internal/              # Private application code
│   │   ├── domain/            # Pure Business Logic (Entities + Ports)
│   │   ├── application/       # Use Cases & Orchestration
│   │   ├── interfaces/        # Adapters (REST, Middleware)
│   │   └── infrastructure/    # Implementations (TiDB, Outbox)
│   └── pkg/                   # Public Shared Code
│
├── frontend/                  # React + Vite
│   └── src/
│       ├── core/              # Domain logic & Hooks
│       └── components/        # UI presentation
│
├── shared/                    # SSoT Definitions
│   └── pkg/                   # Generated Go Models/Constants
│

```

## ⚡️ Quick Start

### Prerequisites
- Node.js 18+
- Go 1.21+
- MySQL/TiDB

### Setup

1.  **Install Dependencies**
    ```bash
    npm install
    ```

2.  **Environment**
    ```bash
    cp .env.example .env
    cp .env.example frontend/.env
    ```

3.  **Apply Control Plane Setup (required before first server start)**
    ```bash
    bash -lc 'source ./scripts/runtime-env.sh && nexus_export_runtime_env "$PWD" && make setup'
    ```

4.  **Run Development Server**
    ```bash
    npm run dev:full
    ```
    Notes:
    - If local `.env` still points `FILE_STORAGE_PROVIDER` at `s3` but you have not exported AWS credentials, the backend startup script now falls back to local filesystem storage automatically so file upload/download can still be verified in local `dev:full`.
    - To force real S3 in local development, export valid `FILE_STORAGE_ACCESS_KEY_ID` / `FILE_STORAGE_SECRET_ACCESS_KEY` or standard `AWS_*` credentials before starting the backend.

    Access:
    - Frontend: `http://localhost:5173`
    - Backend: `http://localhost:3001`
    
### ☁️ Salesforce Integration (Frontend Only)
To develop against a Salesforce environment (Sandbox/Production):

1.  **Configure `.env`**:
    ```bash
    # Point to Salesforce instance (e.g., https://test.salesforce.com or https://my-domain.sandbox.my.salesforce.com)
    REACT_APP_BACKEND_URL=https://test.salesforce.com
    ```
2.  **Restart Frontend**:
    ```bash
    npm run dev
    ```
    The Vite proxy will automatically forward API requests to the configured Salesforce instance.


### Testing & Verification
We enforce strict quality gates.

- **E2E Tests**: `./tests/e2e/runner.sh`
- **Unit Tests**: `npm run test:frontend`
- **Linting**: `npm run lint`
- **Regression planning**: after high-risk issue fixes, classify follow-up coverage using `docs/test-infra/`

## 🔄 Code Generation (SSoT)

If you modify `backend/internal/bootstrap/system_tables.json`, you **MUST** regenerate code:

```bash
make generate
```
This updates Frontend Types, Backend Models, and Constants to ensure synchronization.