Standard Operating Procedures

These SOPs apply to: Frontend application (Next.js 16, hosted on Cloudflare) · Backend API (FastAPI, hosted on Railway) · PostgreSQL database (Railway managed) · AI services (AGIM external, Ollama local)

1. User submits credentials to POST /auth/login
2. Backend verifies credentials, issues JWT access token (30 min) + refresh token (7 days httpOnly cookie)
3. Frontend stores access token in sessionStorage
4. All API requests include Authorization: Bearer <token> header
5. On 401, frontend calls POST /auth/refresh to get new access token

AGIM URL/Key and Ollama URL/Model are managed through System Admin → AI Config and stored in the database. No hardcoded environment variables needed for AI config.

1. Merge feature branch into main via Pull Request.
2. Railway auto-deploys on push to main.
3. Verify deployment in Railway dashboard — check build logs.
4. Smoke test: GET /health → {"status": "ok"}; login with test credentials.
5. Monitor error logs for 10 minutes post-deployment.

Backend: In Railway dashboard → Deployments tab → select previous successful deployment → Redeploy.

Frontend: In Cloudflare dashboard → select previous deployment → Promote to Production.

1. Log in as an existing admin.
2. Navigate to System Admin → Users.
3. Find the target user account.
4. Click Promote to Admin and confirm.

Emergency (database direct):

UPDATE users SET role = 'admin' WHERE email = 'user@example.com';

Navigate to System Admin → Users, select the user, click Delete Account, and confirm.

1. Generate a bcrypt hash for a temporary password:

   import bcrypt
   hash = bcrypt.hashpw(b"TempPassword123!", bcrypt.gensalt()).decode()
   print(hash)

2. Update the database:

   UPDATE users SET password_hash = '<hash>' WHERE email = 'user@example.com';

3. Communicate the temporary password via secure channel; instruct user to change it immediately.

1. Created — user completes 5-step wizard in Blueprint Hub
2. Encrypted — user enters passphrase; AES-256-GCM encryption applied client-side
3. Exported — .hassar file downloaded to user's device
4. Used — uploaded to Jim chat or Review Existing Blueprint for inspection
5. Archived — user retains the file; no server-side storage

1. Inform the user that recovery is not possible.
2. Guide the user to recreate the blueprint using the 5-step wizard.
3. Remind the user to store the new passphrase securely (e.g. password manager).

1. Navigate to System Admin → AI Config.
2. Update: AGIM URL · AGIM API Key · Ollama URL · Ollama Model.
3. Click Save. Changes apply immediately to new AI requests.

1. Check System Admin → Logs for AI-related errors.
2. Verify AGIM service is reachable from the backend server.
3. Verify Ollama is running: curl http://localhost:11434/api/tags
4. Check AI Config — verify API keys and endpoints are correctly set.
5. Test with a simple query through the chat interface.
6. If unresolved, escalate to Level 2 (see Escalation Matrix).

GET /health
Response: {"status": "ok"}

Monitor every 60 seconds. Alert on non-200 responses or response time > 5 seconds.

Navigate to System Admin → Logs. The log table shows timestamp, log level, and message for recent system events.

1. Detect: Uptime monitor alerts or multiple user reports.
2. Acknowledge: Assign incident owner within 15 minutes.
3. Assess: Check Railway/Cloudflare dashboards. Check database status.
4. Communicate: Post status update to stakeholders.
5. Mitigate: Roll back most recent deployment if outage followed a deploy.
6. Verify: Confirm /health returns 200 and core flows work.
7. Post-mortem: Document root cause within 24 hours.

1. Check system logs for AI error messages.
2. Check AGIM service status.
3. Verify Ollama fallback is working.
4. If both failing, check AI Config for misconfiguration.
5. Escalate to AGIM support if AGIM is confirmed down.

1. Check system logs for AUTH event errors.
2. Verify SECRET_KEY environment variable is set.
3. Check database connectivity.
4. If JWT secret was rotated, all sessions are invalidated — users must log in again.

Railway automatic backups: Verify daily automated backups are enabled in Railway project settings.

Manual backup:

pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql

Store backups off-platform (e.g. encrypted S3 bucket). Minimum retention: 30 days.

psql $DATABASE_URL < backup_YYYYMMDD.sql

Test restores quarterly in a non-production environment.

Blueprint files (stored locally by users) · Chat history (stored in user browsers) · Blueprint passphrases (never stored anywhere).

1. Provision new Railway project with PostgreSQL.
2. Restore database from latest backup.
3. Set all environment variables (see Section 3).
4. Deploy backend and frontend from main branch.
5. Verify all services operational.

RTO: 4 hours  ·  RPO: 24 hours

JWT Secret Key

1. Generate new secret: openssl rand -hex 32
2. Update SECRET_KEY in Railway environment variables.
3. Redeploy backend. All existing sessions will be invalidated.

AGIM API Key

1. Rotate key in AGIM dashboard.
2. Update in System Admin → AI Config.

1. Immediately rotate all secrets (JWT, AGIM API key, database password).
2. Invalidate all sessions (JWT secret rotation achieves this).
3. Review system logs for AUTH events to identify affected accounts.
4. Notify affected users.
5. Preserve logs for forensic investigation.

1. Navigate to System Admin → Users.
2. Filter by Role = admin.
3. Remove admin privileges from accounts that no longer require them.