MaskanX Backend

Independent Python and FastAPI backend for MaskanX.

Service Contract

• Default API URL: http://127.0.0.1:8088
• PostgreSQL database: campaign
• Frontend origin: configured with MASKANX_CORS_ORIGINS
• Maskan CRM: connected through its versioned REST API and optional MCP tools

This repository never connects directly to the Maskan CRM PostgreSQL database.

Local Setup

1. Create the database:

   CREATE DATABASE campaign;
   

2. Install dependencies and configure the environment:

   python -m venv .venv
   .\.venv\Scripts\python.exe -m pip install -e ".[dev]"
   npm install
   Copy-Item .env.local.example .env.local
   

3. Migrate, seed, and start:

   npm run local:migrate
   npm run local:seed
   npm run local
   

Open API documentation at http://127.0.0.1:8088/docs when documentation is enabled.

Upgrading from JSON storage

Chats and cron jobs were originally stored as JSON files in the working directory (~/.adclaw/chats.json and ~/.adclaw/jobs.json). PostgreSQL is now the default backend, so those records are no longer read and existing chats, sessions, and scheduled jobs appear to be missing even though nothing was deleted.

Copy them into PostgreSQL once:

npm run local:import-json -- --dry-run   # report what would be imported
npm run local:import-json                # perform the import

The import upserts by id and never deletes, so it is safe to re-run. The JSON files are left untouched as a backup.

Clearing and restoring credentials

Stop MaskanX before clearing credentials. A running app holds its configuration in memory and can rewrite config.json and providers.json after the clear, silently restoring the values that were just removed. The clear script now verifies the result and exits non-zero if anything secret-looking survives.

Credentials live in three places, and all of them are cleared:

• ~/.adclaw.secret/providers.json - LLM provider keys
• ~/.adclaw.secret/envs.json - integration keys
• ~/.adclaw/companies/<id>/ - a per-company copy of both, plus LinkedIn OAuth

Because each company keeps its own copy, an intact company store can be used to recover the active one:

npm run secrets:restore -- --from default --dry-run
npm run secrets:restore -- --from default

Credential files are copied wholesale; config.json is patched surgically, so only missing MCP env values and disabled clients are restored and company-specific settings are preserved. A backup is written to ~/.adclaw.secret/restore-backups/ first.

Commands

Command	Purpose
npm start	Start using .env or injected environment variables
npm run build	Build a Python wheel in dist/
npm run local	Local API with reload
npm run local:migrate	Apply local PostgreSQL migrations
npm run local:migrate:undo	Roll back the newest migration
npm run local:migrate:undo:all	Roll back every migration
npm run local:seed	Add starter data
npm run local:seed:undo	Remove starter data
npm run local:import-json	Import legacy JSON chats/cron jobs into PostgreSQL
npm run secrets:dry-run	Report which credentials a clear would remove
npm run secrets:clear	Clear runtime credentials (creates a backup)
npm run secrets:clear:all	Also blank secret lines in .env files (creates a backup)
npm run secrets:delete:all	Clear everything including .env files (creates a backup)
npm run secrets:delete:all:no-backup	Same, with no backup - irreversible
npm run secrets:restore	Restore credentials from an intact company store
npm run local:reset	Rebuild and seed the local schema
npm run dev	Development API with reload
npm run dev:migrate	Apply development migrations
npm run dev:reset	Reset the development schema
npm test	Run Pytest using .env.testing
npm run test:migrate	Apply test database migrations
npm run test:reset	Reset the test schema
npm run prod	Start the production API
npm run prod:migrate	Apply production migrations
npm run prod:seed	Apply production starter data

The command names match the platform deployment contract. They invoke the native MaskanX Python migration runner, not Sequelize.

Docker

Copy-Item .env.local.example .env
docker compose up -d --build

For a managed PostgreSQL deployment, provide DATABASE_URL through the hosting secret manager and run npm run prod:migrate as a release step.