Name		Name	Last commit message	Last commit date
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
README.md		README.md
SECURITY.md		SECURITY.md
app.ts		app.ts
auditLog.ts		auditLog.ts
auth.routes.ts		auth.routes.ts
auth.test.ts		auth.test.ts
auth.ts		auth.ts
ci.yml		ci.yml
createCrudRouter.ts		createCrudRouter.ts
env.ts		env.ts
errorHandler.ts		errorHandler.ts
health.routes.ts		health.routes.ts
health.test.ts		health.test.ts
index.ts		index.ts
jest.config.js		jest.config.js
logger.ts		logger.ts
package.json		package.json
payments.ts		payments.ts
rbac.ts		rbac.ts
roles.ts		roles.ts
schemas.ts		schemas.ts
server.ts		server.ts
store.ts		store.ts
tsconfig.json		tsconfig.json
validate.ts		validate.ts

Repository files navigation

FreClean API

Backend API for the FreClean ecosystem, covering authentication, customers, bookings, orders, products, inventory, staff/teams, entrepreneurs, payments (cash/card/Web3), reviews, notifications, reports, analytics, and audit logs.

Part of the FreClean ecosystem (see freclean-website, freclean-admin, freclean-dapp, freclean-payment, freclean-docs).

Status

In development. Runs against an in-memory demo data store (src/data/store.ts) so the API is fully runnable and testable without a database. Swap in a real persistence layer (PostgreSQL, via freclean-data) before production use. The CRUD factory (src/core/createCrudRouter.ts) is written so that swap does not require touching route logic.

Tech stack

Node.js + TypeScript + Express, zod for validation, jsonwebtoken + bcryptjs for auth, winston for logging, helmet + express-rate-limit for baseline security, jest + supertest for tests.

Getting started

npm install
cp .env.example .env
npm run dev        # http://localhost:4000

npm test            # run the test suite
npm run lint         # eslint
npm run typecheck    # tsc --noEmit
npm run build        # compile to dist/

API structure

All business routes are mounted under /api. Auth routes are under /auth. Health check at /health.

Path	Resource	Notes
/auth/register, /auth/login	Auth	Self-registration limited to customer / entrepreneur roles
/api/users	Users	Staff role changes require founder or management
/api/customers	Customers
/api/services	Services
/api/bookings	Bookings
/api/orders	Orders
/api/products	Products	Lifecycle status: development / prototype / available / discontinued / planned
/api/inventory	Inventory
/api/staff	Staff
/api/teams	Cleaning teams
/api/entrepreneurs	Entrepreneur program
/api/payments	Payments	Custom router, see below
/api/assets	Supported Celo assets registry	Finance-role access only
/api/reviews	Reviews
/api/notifications	Notifications
/api/reports	Reports	Read-only
/api/analytics	Analytics	Read-only
/api/audit	Audit log	Read-only, founder/management only

Every resource above supports GET /, GET /:id, POST /, PATCH /:id, DELETE /:id, gated by role (see src/core/roles.ts).

Payments: status transitions

/api/payments cannot jump straight to confirmed. Status must advance one step at a time:

requested → pending → detected → verified → confirmed

or move to a terminal state: failed, expired, refunded. A Web3 payment cannot be confirmed without a transaction hash. See src/modules/payments.ts.

Authentication & roles

Send Authorization: Bearer <token> on every /api/* request. Roles: founder, management, finance, operations, product_management, cleaning_staff, support, entrepreneur, customer. Permission tables live in src/core/roles.ts and are applied per resource in src/modules/index.ts.

Data integrity rule

No invented business facts. Seed data in src/data/store.ts is explicitly marked _demo: true and documented as DEMO DATA: NOT REAL CUSTOMER DATA. The Supported Assets Registry (/api/assets) ships empty/placeholder until a real Celo asset is verified; see freclean-payment and freclean-docs.

Roadmap for this repo

Replace in-memory store with PostgreSQL (freclean-data)
Wire freclean-payment's Celo verification service into the payments transition endpoint
Add npm audit / Dependabot to CI
Add integration tests for every resource, not just auth/health
Add OpenAPI/Swagger documentation