Skip to content
CeloHaiTiFreCleanPublic
forked from FreClean/FreClean

About

FreClean core backend, API, database and business logic for the FreClean platform (bookings, products, inventory, orders, Crypto/USDT/Cash payments).

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

FreClean Core

file_000000006e6481f5ad01e503c55c2326

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.

Stack

  • Node.js 20+ / TypeScript
  • Express
  • PostgreSQL (raw SQL migrations, pg driver no hidden ORM magic)
  • JWT-based auth, RBAC middleware
  • Vitest for tests

Getting started

cp .env.example .env
npm install
npm run db:up
npm run db:migrate
npm run dev

The 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.

Structure

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

Payment policy

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.

Disputes and complaints

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.

Security

  • 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.md for the full checklist this repo is audited against.

Production readiness notes

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.

Render health checks

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 /health as an HTTP 200 liveness signal only.
  • Treat /health/ready as database readiness: HTTP 200 means SELECT 1 succeeded; 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.

Legal & Compliance Status

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.

License

MIT - see LICENSE.

About

FreClean core backend, API, database and business logic for the FreClean platform (bookings, products, inventory, orders, Crypto/USDT/Cash payments).

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages