Initial commit: MaskanX backend
Independent FastAPI backend for the MaskanX agentic growth platform. Includes the agent runtime, MCP client integrations (Meta Ads, LinkedIn, HubSpot, Tavily, Exa, xAI, Citedy, image generation), PostgreSQL storage for chats and cron jobs, provider and secret management, and the CLI. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
AFFAANh
@@ -0,0 +1,128 @@
|
||||
# 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:
|
||||
|
||||
```sql
|
||||
CREATE DATABASE campaign;
|
||||
```
|
||||
|
||||
2. Install dependencies and configure the environment:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
```powershell
|
||||
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.
|
||||
Reference in New Issue
Block a user