Backend / API / Database / Business Logic for the FreClean ecosystem (Cleaning Services, Cleaning Products, Fragrance / Scented Products, bookings, orders, inventory, payments, disputes, Entrepreneurship).
This is the canonical core repository. It owns all business rules and is the only service allowed to write to the production database.
- Node.js 20+ / TypeScript
- Express
- PostgreSQL (raw SQL migrations,
pgdriver no hidden ORM magic) - JWT-based auth, RBAC middleware
- Vitest for tests
cp .env.example .env
npm install
npm run db:up
npm run db:migrate
npm run devThe local PostgreSQL database runs through Docker Compose on localhost:5432.
Use npm run db:down to stop it while preserving the named database volume,
or docker compose down -v when you intentionally want to delete local data.
src/
auth/ registration and login
bookings/ booking lifecycle
disputes/ complaints, case workflow, communication, and audit integration
roles/ authorization and RBAC
payments/
crypto/ USDT transaction verification for four mainnets
notifications paid-payment email outbox delivery
database/migrations/ versioned SQL migrations
scripts/ operational scripts
docs/ architecture and payment/security documentation
The only supported customer payment options are USDT on FreClean-approved
BEP20, TRC20, Solana, or Celo networks, and the separate confirmed CeloHT DApp
route. Cash is accepted in person at authorized FreClean physical points of
sale only; it is never offered online or remotely. New payment requests use
USDT or CELOHT_DAPP; legacy payment rows remain available for historical
recordkeeping. USDT transfers are checked server-side, but an authorized
administrator must manually confirm receipt before the payment or
order/booking can become paid. See
docs/payments.md for the API, configuration, migration,
verification details, production gates, and acceptance checklist.
USDT checkout is disabled by default. This repository does not include website checkout UI or product order creation; the public website is a separate repository. CeloHT settlement is manually checked outside this API before an administrator confirms it.
Public contact and service enquiries are saved together with a durable Resend
notification. The Core worker retries delivery to contact@freclean.com and
uses the visitor's email as Reply-To. Configure CONTACT_EMAIL,
RESEND_API_KEY, and a verified RESEND_FROM_EMAIL in the deployment secret
manager; provider credentials are never sent to website clients.
The canonical dispute API is under /api/disputes. It supports authenticated
case creation, ownership-filtered retrieval, explicit dispute permissions,
controlled status transitions, customer/internal communication visibility, and
audit history. See docs/disputes.md for the contract and
the boundaries that still require external infrastructure, including private
evidence storage and refund-provider integration.
- Server-side authorization only never trust frontend role claims.
- Secrets live in environment variables, never in git. See
.env.example. - Production configuration is validated before startup; missing required secrets or invalid payment config fail the process.
- Refresh tokens are validated against the current active account and roles. Token rotation and revocation are not yet implemented.
- See
docs/security.mdfor the full checklist this repo is audited against.
This repository is the authoritative core of the FreClean architecture. It enforces the business rules, writes to PostgreSQL, verifies payment state, and is the only service allowed to issue authoritative payment/order state.
Use the Render service URL for HTTPS smoke tests:
- Liveness:
GET https://freclean.onrender.com/health - Readiness:
GET https://freclean.onrender.com/health/ready - Configure Render's Health Check Path as
/health. - Treat
/healthas an HTTP 200 liveness signal only. - Treat
/health/readyas database readiness: HTTP 200 meansSELECT 1succeeded; HTTP 503 means PostgreSQL is unavailable. - Do not put database URLs or other credentials in health-check paths, responses, or logs.
The production CORS origin is https://freclean.com. This repository does not contain a Supabase integration or authentication client, so Supabase configuration is not part of this service's runtime.
External dependencies still required for a full regulated deployment include private evidence storage and malware scanning, refund and notification providers, the customer/staff frontend repositories, payment-route operational checks, legal review for jurisdictional compliance, tax registration review, product compliance review, and a formal security audit before production go-live.
FreClean is currently formalizing and documenting its legal and operational framework in Haiti.
Current status:
- NIF: In process
- NINU: In process
- CIP: In process
- Registre du Commerce: In process
- Commercial Name Certificate: In process
- Patente: In process
- Company Statutes: Pending legal structure
- Business Bank Account: In process
- Insurance: In process
- FreClean Trademark: Yes
- Client Contracts: Not yet available
- Supplier Contracts: In process
Legal Structure: Pending determination.
These statuses are informational and do not represent legal advice or confirmation that pending registrations, licenses, certificates, or compliance obligations have been completed.
The full public documentation register is in
docs/legal/document-register.md. Confidential
evidence belongs in an access-controlled private data room, not in this public
repository.
MIT - see LICENSE.