Skip to content

feat: add stack contract compliance sections #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
henrylove0 merged 2 commits into from
Jun 10, 2026
Merged

feat: add stack contract compliance sections #35

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d5f87b4
feat: add stack contract compliance sections to CONTRACTS.md
henrylove0 Jun 10, 2026
36e6a7c
fix: await app.close() in command bootstrap to prevent cache:flush hang
henrylove0 Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions CONTRACTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,9 +143,51 @@ Exe CRM does not currently expose its own MCP server. It is consumed as a standa

> **Note:** `twenty-companies.com` is an upstream (Twenty) service. It is not Exe-controlled. Customer data (company names) is sent to this service for enrichment. If this conflicts with data sovereignty requirements, disable company enrichment or replace the `TWENTY_COMPANIES_BASE_URL` constant in `packages/twenty-shared/src/constants/TwentyCompaniesBaseUrl.ts`.

## Stack Contract Compliance

### GoTrue Security Policy

When `GOTRUE_URL` is configured for external auth:
- Signup endpoint MUST be disabled on the GoTrue instance
- `MAILER_AUTOCONFIRM` must be set to `false` (users confirm email)
- JWT audience MUST match `GOTRUE_JWT_AUDIENCE`

### UI Section States

All major UI sections (tables, forms, sidebars, panels) must implement:
- **loading** — data is being fetched
- **ready** — data loaded and displayed
- **empty** — no data exists (distinguish from error)
- **error** — fetch/operation failed with human-readable message and retry affordance
- **degraded** — partial function available, names what is unavailable

CRM tables/API contracts must fail with explicit degraded/error states, not skeleton forever.

### Progress Events

Long-running operations (workflow execution, data imports) must emit events with:

| Field | Required | Description |
|---|---|---|
| `operationId` | Yes | Unique ID for the operation |
| `phase` | Yes | Current phase name |
| `label` | Yes | Human-readable description |
| `status` | Yes | queued / running / blocked / degraded / succeeded / failed / cancelled |
| `updatedAt` | Yes | ISO timestamp |
| `current` / `total` | Optional | Only when accurately measurable |

Fake, timer-only, or cosmetic progress is forbidden.

### Error Forwarding

All 5xx backend errors are forwarded to exe-monitor-hub via `ErrorForwardingFilter` and `ErrorForwardingService`.
Configured by `MONITOR_ERROR_URL` and `ERROR_REPORTING_ENABLED` (default: `true`).
Comment on lines +183 to +184

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document the required monitor URL

This states that 5xx backend errors are forwarded and that reporting is enabled by default, but ErrorForwardingService.forwardError returns without sending anything whenever MONITOR_ERROR_URL is unset. A deployment following this contract can leave the URL out and silently get no exe-monitor-hub reports while believing the default enables forwarding; please qualify this as "when MONITOR_ERROR_URL is configured" or mark that variable required for forwarding.

Useful? React with 👍 / 👎.

Fire-and-forget with 5-second timeout.

## Cross-Repo Dependencies

| Dependency | Relationship |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **exe-os** | Orchestration layer. Launches exe-crm via Docker Compose. Reads `SERVER_URL` to proxy API calls. |
| **exe-db** | Optional shared PostgreSQL instance. When using exe-db, set `PG_DATABASE_URL` to point at the exe-db host instead of the bundled `db` container. |
| **exe-monitor-hub** | Receives error/degradation alerts via error-forwarding service. |
Loading