What is this?

The Intellens Admin Console is the internal operations tool for Intellens staff. It gives you direct, audited access to the production database through a purpose-built UI — creating clients, managing users, onboarding suppliers, inspecting what users see, and reviewing the full change history.

It runs locally on your machine over an SSM tunnel to production RDS. The PRODUCTION badge is intentional — there is no staging version of this tool.

Layout

• Left panel — Client list + search. Click a client to open it.
• Right panel — Globe view (default) or the selected client's full profile.
• Header right — Your operator name (click to change), Guide, Log out.
• Recent Activity — Scrollable audit feed at the bottom of the right panel.

Quick-start for onboarding a new client

1. Click + New client → fill company name, reporting currency, contact email → Save.
2. Open the client → scroll to Users → Add user → set role to admin for the primary contact.
3. Scroll to Suppliers → Bulk import → download template, fill it, drag it back.
4. Send the user their password (copied to clipboard on create) and the login URL: https://app.intellens.ai

Client list

• Search filters by company name in real time.
• Badges on each card flag gaps: no users no suppliers no location — these are soft warnings, not blockers.
• The Intellens card (blue border) is the internal org. It works the same as client cards but cannot be deleted.

Creating a client

• Click + New client. All fields except Company name are optional at creation.
• Reporting currency — drives how portfolio values display in the app. Defaults to EUR.
• Alert sensitivity — aggressive / balanced / conservative. Controls which risk alerts surface in the app. balanced is the usual default.
• Address — type to search worldwide; pick a suggestion to auto-fill lat/lng/altitude.
• The lat/lng fields accept manual entry if the geocoder doesn't find the address.

Editing a client

• Open a client → all fields are editable inline → Save changes.
• Logo — paste a URL or click the upload icon to upload a file (stored in S3, served as a CDN URL).
• Changes take effect in the app on next page load.

Globe view

• Every client with lat/lng appears as a marker. Click a marker to open that client directly.
• Clients without coordinates appear in the list but not on the globe. Add an address to make them visible.

User roles

Creating a user

• Open a client → Add user → fill name and email → click Generate to auto-generate a strong password.
• On save the password is copied to clipboard automatically. Paste it into your password manager or send it securely to the user.
• The password is hashed immediately — it cannot be recovered after this point. Use Reset pw if the user loses it.

Managing users

• Edit — inline form: name, email, role, position, phone, image URL.
• Reset pw — mints a new random password and copies it to clipboard. The user must be told the new password out-of-band.
• View as — opens a shadow session (see Shadow profiling tab).
• Delete — soft delete. The user is hidden from the app immediately but the record is retained. Recoverable from Recent Activity using ↩ Undo.

Last active

Shows the most recent successful login timestamp. Never logged in means the user hasn't used their credentials yet — common for newly created accounts.

Adding a single supplier

• Open a client → Add supplier → fill at minimum the Legal name.
• Criticality tier — 1 (most critical) to 5 (least). Tier 1 suppliers receive the most thorough risk scoring.
• Country — used as the geographic anchor for all risk models (conflict, climate, geopolitical, etc.).
• Coordinates fill in automatically via the geocoding cron within 24 hours of import.

Bulk import

1. Click Bulk import → Download template (.csv).
2. Fill it in. Required column: Company*. Optional: Email, Type, Importance, ABC, Address.
3. Drag the completed file back onto the drop zone, or paste rows directly from Excel/Sheets.
4. Review the preview — green rows will be imported, red rows have errors.
5. Click Import N suppliers. The operation is atomic: either all succeed or none are written.

After import

• Risk scoring runs on the next scheduled cron (daily 08:00 UTC). New suppliers appear in the app immediately but scores arrive the next day.
• To trigger scoring immediately: run the composite_supplier_risk_timeline cron manually from AWS Lambda.
• Edit — inline form: name, tier, country, address.
• Delete — soft delete. Recoverable from Recent Activity using ↩ Undo.

What is shadow profiling?

Shadow profiling lets you open app.intellens.ai exactly as a specific user would see it — their suppliers, risk scores, alerts, and settings — without knowing their password or disrupting their session.

It is used for: customer support calls, onboarding reviews, reproducing reported bugs, and QA on a specific client's data.

How to open a shadow session

1. Open a client → scroll to Users → click View as next to any user.
2. A prompt asks for a reason. This is logged to the audit trail and emailed to the user. Write something meaningful: "Customer support — user can't see their alerts" or "Onboarding review for Acme Corp".
3. Two things happen simultaneously:
   • A new tab opens with app.intellens.ai loaded as that user.
   • The data panel opens in this console showing that user's suppliers and alerts for quick reference.

Security model

What the user sees

The target user receives an email like: "An Intellens administrator (lm@intellens.ai) opened a shadow session on your account — Reason: Customer support call — 2026-06-26 14:03 UTC."

Their own session is not affected. They stay logged in. The shadow session is entirely separate.

What is logged

Every mutation made through this console is written to settings.audit_log in real time. The feed at the bottom of the right panel shows the 50 most recent entries.

↩ Undo

The ↩ Undo button appears on delete_user and delete_supplier rows. Clicking it calls the restore endpoint and creates a restore_* audit entry. The operation is instant and writes to production — there is no confirmation prompt.

Reading the detail

Each activity row shows: who was affected (name + email + client), what fields changed (for updates), and when. Timestamps are relative ("3 min ago") — hover for the exact UTC time.

What is this?

The Lambda monitor (left panel, λ button) is an at-a-glance view of every intellens-* Lambda's execution status and recent failures, grouped by SAM stack (action / fact / operations). It is read-only — it queries CloudWatch, CloudWatch Logs, and Lambda; it never invokes or modifies anything.

Status

Each function carries a text status badge (colour and word, so it reads without relying on colour). Failing / warning / unknown rows are also tinted with a coloured left border.

Why two kinds of "error": CloudWatch's Errors metric only counts invocations that failed. A function can catch an exception, log it as ERROR, and still return success — invisible to the metric. This board counts both (the ⚑ flag = logged-only), so a run that quietly logged errors can't hide behind a healthy badge.

Columns

• Last run — how long ago the function last logged anything, relative (hover for exact UTC). An overdue pill appears if a daily+ job has gone quiet.
• Inv 24h — invocations over 24h (hover for the 7-day count).
• Errors — failed-invocation count (red) · logged ERROR-line count (amber ⚑, + if the 100-line cap was hit; n/a = logs couldn't be read). Either one flags the function failing. A red ↑ means more failed invocations than the function's own 7-day daily average (trending up). Hover the cell for when it last failed (UTC).
• Last output — the most recent "what it did" line parsed from the logs (e.g. "148 rows upserted", "3 countries processed", "0 processed / no new") — answers did it actually update anything, and how much. Hover for the full line.
• Avg dur — average execution duration over 24h. A ↑ means >1.5× the 7-day norm (slower than usual); a ↓ means <half of it (much faster — often a silent no-op / early exit). Only shown for functions with a stable cadence, so rare jobs aren't false-flagged.
• Alarm — state of any CloudWatch alarm that names this function (hover for the alarm name, reason, and how long it's been in ALARM). Alarms not tied to a function appear in the firing-alarms panel and the "Needs attention" list, tagged standalone.

Firing-alarms panel — above the tables, every alarm currently in ALARM is listed with its reason. Alarms not tied to a specific function (custom-metric / business alarms) are tagged standalone so they can't slip through the per-function view.

Triage header

The board leads with a hero count ("3 functions failing" / "2 need attention" / "All N healthy"), a chip strip, the firing-alarms panel, and a Needs attention list of the worst offenders with the reason each is flagged — click one to jump straight to its row. Show problems only collapses the board to failing/warning/unknown functions. Rows are sorted worst-first within each stack.

Drill-down & quick actions

Click any row to expand it: a one-line summary of what the function does, a status line with 24h + 7d counts, avg/peak duration and the last run's timing, the full Last output, every alarm with its reason, quick actions (Logs↗ / Function↗ / Metrics↗ deep-link into the AWS console in a new tab — read-only, authorised by your own AWS session; Copy name), and the last ~25 ERROR / Exception / Traceback / "Task timed out" lines from /aws/lambda/<function>. Use ↻ Refresh to re-pull (results are briefly server-cached, so a burst of refreshes is cheap). The console stays read-only — it never invokes or changes anything.

Requires the console's IAM role to allow lambda:ListFunctions, cloudwatch:GetMetricData, cloudwatch:DescribeAlarms, logs:DescribeLogStreams, logs:FilterLogEvents, logs:GetLogEvents (see CONSOLE_LAMBDA_DASHBOARD.md).

How this console is secured

What this console cannot do

• It cannot modify the audit log — entries are append-only.
• It cannot permanently delete users or suppliers — deletes are always soft (recoverable).
• It cannot access the JWT secret or mint arbitrary production JWTs outside of the shadow flow.
• It cannot be reached from any machine other than the one running it.

If something goes wrong

• Wrong change made — check Recent Activity and use ↩ Undo if available. For other changes, contact the DB admin to revert directly.
• Locked out — wait 15 minutes, then try again. The lockout is per email, not per IP.
• SSM tunnel dropped — restart the tunnel from an Administrator PowerShell: see CLAUDE.md for the exact command.
• Port 8765 in use — kill the process holding the port: netstat -ano | findstr 8765 then taskkill /PID <pid> /F.