Arctx Backend

active · updated 2026-08-01 02:06

Description

The Arctx platform backend (formerly the Projecto spike): Next.js + Neon + MCP server. Being hardened toward personal-production MVP: project groups, roles (owner/admin/member/viewer), Clerk OAuth.

Charter

Tasks

• doneH4: UI — sidebar group nesting + group page with rollup
  todoin progressdoneSet
• doneH3: update_project MCP tool (name, description, repo_url, charter) — gap hit 3x today
  todoin progressdoneSet
• doneH1: project_groups — schema (table + projects.group_id FK), migration SQL for Neon
  todoin progressdoneSet
• doneH2: MCP tools — create_group, assign_project_to_group, get_group_briefing
  todoin progressdoneSet
• todoH9: Post-OAuth cleanup — revoke legacy bearer, rotate Neon password, rename repo to arctx-backend
  todoin progressdoneSet
• todoH8: save_project tool — atomic capture incl. TASK RECONCILIATION sweep; /save prompt
  todoin progressdoneSet
• todoH7: Claude Desktop native connect test (Add Custom Connector, URL only)
  todoin progressdoneSet
• todoH6: OAuth 2.1 via Clerk on /api/mcp + /.well-known endpoints; dual-auth transition
  todoin progressdoneSet
• todoH5: Clerk app + Organizations; users/workspaces/workspace_members(role) scaffolding
  todoin progressdoneSet
• doneResume from Codex, verify full context
  todoin progressdoneSet
• doneWork a session in Claude Code, log summary
  todoin progressdoneSet
• doneConnect Claude Code via MCP
  todoin progressdoneSet

Timeline — every tool, one ledger

• claude-ai · session_summary · 2026-08-01 02:06
  H5 PROGRESS - CLERK PRODUCTION INSTANCE LIVE ON arctx.ai. Created production instance (cloned from dev) against apex arctx.ai so it covers all subdomains including app.arctx.ai. Five CNAMEs entered at GoDaddy and verified: clerk->frontend-api.clerk.services, accounts->accounts.clerk.services, clkmail->mail.jy8kts137ujf.clerk.services, clk._domainkey->dkim1.jy8kts137ujf.clerk.services, clk2._domainkey->dkim2.jy8kts137ujf.clerk.services. Clerk dashboard now reports: Primary domain VERIFIED, DNS configuration VERIFIED, SSL certificates ISSUED. Independently confirmed: valid certs on clerk.arctx.ai and accounts.arctx.ai (exp 2026-10-30); GET https://clerk.arctx.ai/v1/environment returns 200 with instance_environment=production; sign_in_url=https://accounts.arctx.ai/sign-in. Clerk keys (pk_live/sk_live) already stored as Vercel env vars on projecto-spike: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (not sensitive, Production) and CLERK_SECRET_KEY (sensitive, Production). NOTE ON TTL: GoDaddy defaulted the new records to 1 Hour; apex A record is 1/2 Hour. User preference recorded: use 1/2 Hour for FUTURE records. Existing TTLs deliberately left unchanged - no functional impact, and Clerk verification already passed. REMAINING FOR H5 (all in Clerk dashboard, PRODUCTION instance - settings do NOT propagate from dev): (1) Organizations -> enable, Membership Required (Workspace = Clerk Organization, 1:1); (2) Roles & Permissions -> add 'owner' and 'viewer' to Clerk's default admin/member, with owner as Creator Role holding Manage members/Read members/Delete Organization; (3) OAuth applications -> enable Dynamic Client Registration (required by most MCP clients; note it creates a public unauthenticated registration endpoint and permanently enforces the consent screen) and enable user:org:read scope (yields org_id claim so the MCP server can resolve which workspace a request belongs to). ALSO PENDING: confirm Deployment Protection is OFF on projecto-spike so /.well-known OAuth metadata is publicly reachable. THEN H6: install @clerk/nextjs + @clerk/mcp-tools, wrap existing mcp-handler with withMcpAuth + verifyClerkToken, add /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp, dual-auth transition.
• claude-ai · decision · 2026-08-01 00:33
  DECISION - CLIENT CONFIG MIGRATION DEFERRED TO H6. Rather than repointing MCP clients to app.arctx.ai now and re-authenticating again after OAuth ships, each client will be touched exactly ONCE during H6: update URL and complete OAuth consent in the same pass. The legacy bearer token keeps working on BOTH hostnames until H9 revokes it, so nothing breaks in the interim. CARRY-FORWARD INSTRUCTION FOR H6: register every client against https://app.arctx.ai/api/mcp — NOT projecto-spike.vercel.app — because OAuth dynamic client registration and token audience bind to the hostname the client registers against. Clients to migrate: Claude Code, Manus, Claude Desktop (mcp-remote bridge, or native connector once OAuth is live).
• claude-ai · session_summary · 2026-08-01 00:28
  DOMAIN CUTOVER COMPLETE — arctx.ai is live and Arctx now runs on its own domain. Registrar identified via .ai registry WHOIS = GoDaddy (privacy: Domains By Proxy; created 2025-02-22, expires 2027-02-22). Domain had been delegated to Atom.com marketplace nameservers plus a stray verification-*.ns101.verify.hn NS entry. User delisted from Atom + Afternic and switched nameservers to GoDaddy defaults (ns29/ns30.domaincontrol.com), clearing the stray NS. Vercel domains added and externally verified: arctx.ai -> arctx-landing via A @ 216.198.79.1 (Vercel's NEW recommended IP, not legacy 76.76.21.21); www.arctx.ai -> 308 PERMANENT redirect -> arctx.ai (apex chosen as canonical); app.arctx.ai -> projecto-spike via CNAME 8153f07bffe92644.vercel-dns-017.com. All Let's Encrypt certs issued and verified. FINAL URL MAP: landing https://arctx.ai | product https://app.arctx.ai | MCP endpoint https://app.arctx.ai/api/mcp (verified live: 13 tools respond; list_groups returns the Arctx group with both member projects). ACTION REQUIRED - CLIENT CONFIG MIGRATION: all MCP clients still point at https://projecto-spike.vercel.app/api/mcp. Both hostnames work simultaneously so nothing is broken, but Claude Code, Manus, and the Claude Desktop mcp-remote bridge should be repointed to https://app.arctx.ai/api/mcp BEFORE H6, because OAuth dynamic client registration binds clients to the hostname they register against. NOTE: intermittent SSL EOF observed from external sandboxes immediately after cert issuance on both www and app - transient edge propagation, resolves on retry. NEXT: Clerk production instance against arctx.ai -> its DNS records at GoDaddy -> Organizations (membership required) -> roles owner/admin/member/viewer -> dynamic client registration + user:org:read scope -> keys into Vercel env vars. Also pending: confirm Deployment Protection is OFF on projecto-spike so /.well-known OAuth metadata is publicly reachable for MCP client discovery.
• claude-ai · note · 2026-07-31 17:37
  CORRECTION to the prior 'PRODUCT PHASING' decision entry — supersedes its COPY NOTE. The word 'Orchestrate' was included in the Phase 1 tagline in error (user confirmed it should not have been there). Verification performed: 'Orchestrate' does NOT appear in landing headline v7 (committed source), does NOT appear anywhere in the arctx-landing app/ directory. It appears 3x in the architecture proposal, but always meaning MULTI-MODEL ORCHESTRATION (assigning any provider's model per workspace/project/task/role, BYOK-first) — a Phase 1 capability — NOT agent-to-agent orchestration, which is Phase 2. The two senses of the word must be kept distinct in all product copy and tier definitions. CORRECTED PHASE 1 TAGLINE: 'Save, Organize, Synchronize, Manage & Connect ALL of your Ai Projects from one Centralized Workspace' PHASE 2 TAGLINE (as provided, pending confirmation that it retains 'Orchestrate'): 'Save, Organize, Synchronize, Orchestrate, Manage & Connect ALL of your Ai Projects & Agents from one Centralized Workspace' RESULTING PROPERTY: if Phase 2 retains 'Orchestrate', the delta between the two taglines is exactly two additions — 'Orchestrate' and '& Agents' — and both are Phase 2 capabilities. That makes the tagline pair a clean tier differentiator with no overlap. OPEN QUESTION: confirm Phase 2 retains 'Orchestrate'. NOTE ALSO VERIFIED: the arctx-landing Vercel project currently has deployment protection enabled (external fetch returns Vercel login). Relevant before public launch / arctx.ai domain cutover.
• claude-ai · decision · 2026-07-31 17:30
  PRODUCT PHASING DEFINED BY USER (verbatim taglines): PHASE 1 (current build): 'Save, Organize, Synchronize, Orchestrate, Manage & Connect ALL of your Ai Projects from one Centralized Workspace' PHASE 2: 'Save, Organize, Synchronize, Orchestrate, Manage & Connect ALL of your Ai Projects & Agents from one Centralized Workspace' — capability: different LLM agents can converse and work together; a lead/master model is established, then other LLM models/vendors are assigned as sub-agents. ARCHITECTURAL IMPLICATION (analysis): Phase 2 changes Arctx's system category, not just its feature set. Phase 1 = PASSIVE state layer (Arctx stores; external tools read/write via MCP; humans are the only actors). Phase 2 = ACTIVE orchestration layer (Arctx invokes models directly and mediates agent-to-agent work). New subsystems required: (1) agent registry — agents as first-class entities with vendor, model, credentials (BYOK, already anticipated in Phase 1 proposal), capability profile; (2) delegation graph — lead/master agent + assigned sub-agents, task assignment and result-return semantics; (3) inter-agent communication, two viable patterns: lead-as-orchestrator calling sub-agents as tools (synchronous, MCP-native, simpler) OR shared ledger/blackboard (asynchronous — context_entries is already ~80% of this pattern, source_tool extends naturally to source_agent); (4) execution runtime — model invocation, retries, timeouts, token budgets, cost caps, termination conditions; NONE of this exists today; (5) agent-to-agent interop protocol evaluation (MCP is client->server; agent-to-agent standards are a separate and fast-moving area — verify current landscape at Phase 2 design time). CONFLICT TO REVISIT AT PHASE 2 BOUNDARY: the approved Phase 1 role model states 'MCP connections inherit the authenticated human's role — no separate agent accounts.' Phase 2 requires agent identities with independently scoped permissions (a sub-agent should not necessarily hold Owner rights). That decision must be explicitly revised, not silently outgrown; the four human tiers (owner/admin/member/viewer) remain valid as the human axis. PHASE 1 ASSETS THAT CARRY FORWARD: context_entries ledger (blackboard substrate), project_groups (scope boundary for multi-agent work), MCP server (sub-agents can already read/write state — what is missing is invocation, not access). COPY NOTE: the word 'Orchestrate' appears in the Phase 1 tagline but describes a Phase 2 capability. Also noted: landing headline v4 briefly carried '& Agents' and it was removed in v5 — which matches correct sequencing (do not market Phase 2 capability during Phase 1).
• claude-ai · finding · 2026-07-31 17:23
  INCIDENT + FIX (resolved): after the H4 deploy, /projects/[id] returned 404 while / and /groups/[id] returned 200. Root cause: Vercel file-upload deploys (deploy_to_vercel) replace the ENTIRE file set for the deployment — the H4 payload omitted src/app/projects/[id]/page.tsx, so that route did not exist in the built output. Not a data or DB issue; all rows intact. FIX: redeployed with the complete 13-file set (dpl_9AYBHuv2xn8PyL9Z2ozuvY169fRH); all three project pages verified 200 with Set group selector and timeline rendering, group page and home also 200, MCP tools healthy. STANDING RULE going forward: every file-upload deploy must include the full file manifest, never just changed files. This is also an argument for restoring the git-linked deploy path at the OAuth/repo-rename milestone (H9) so deploys are diffs against the repo rather than full uploads.
• claude-ai · session_summary · 2026-07-31 15:37
  H4 SHIPPED: UI group nesting live at projecto-spike.vercel.app. Home page now renders per-group sections (amber group link -> /groups/[id], member cards indented with left rule), 'Ungrouped projects' section, and a new-group creation form. New /groups/[id] page renders the visual rollup: member project cards with status dot, open-task count, and last ledger entry snippet, plus MCP hint. Project pages gained a 'Set group' selector. New server actions: createGroup, assignProjectGroup. Deployed dpl_7iNDibqAg3EnHxBoh96Fzc1WNdwH; verified live (Arctx group renders with both member projects). Code parity note: UI files + route.ts/core.ts commit to repo still owed — deployed build is source of truth. NEXT: H5 (Clerk app + Organizations + users/workspaces/workspace_members scaffolding — needs user to create Clerk account and add two env vars), then H6 OAuth.
• claude-ai · session_summary · 2026-07-31 15:25
  H1-H3 SHIPPED AND VERIFIED LIVE. (1) Schema: project_groups table + projects.group_id FK migrated on Neon (drizzle/0001_project_groups.sql, applied directly). (2) Five new MCP tools deployed (server v0.2.0, 13 tools total): create_group, list_groups (added beyond spec for UX), assign_project_to_group, get_group_briefing (rollup: per-project status/open-task-count/latest-session), update_project (name/description/charter/repo_url/status — supersedes update_project_status which is retained for compatibility; deprecate at OAuth milestone). (3) Live verification: 'Arctx' Project Group created (24833cc1) containing Arctx Backend + Arctx Landing Page; rollup briefing composed correctly. Code committed: projecto-spike@3e11e30 (schema + migration; route.ts/core.ts commit pending next session — deployed build is source of truth meanwhile). NEXT: H4 UI group nesting, then H5 Clerk, H6 OAuth. User's Zero2CEO group creatable on demand once those projects exist.
• claude-ai · note · 2026-07-31 15:04
  Project renamed: 'Projecto Spike' -> 'Arctx Backend' (via direct DB update; no update_project MCP tool exists yet — this rename is itself evidence for backlog item: update_project tool covering name, description, repo_url, charter). This project now tracks the Arctx platform backend as it hardens from spike to personal-production MVP per the approved plan: (1) project_groups, (2) roles, (3) Clerk OAuth. Repo remains github.com/jeremynhart/projecto-spike for now — rename to arctx-backend at the OAuth milestone to avoid breaking the Vercel git link mid-build. Future structure: 'Arctx' Project Group will contain Arctx Backend + Arctx Landing Page (+ eventual Arctx Frontend if split).
• claude-ai · decision · 2026-07-31 15:02
  SPIKE -> MVP HARDENING PLAN (user approved, priority order): (1) ORGANIZATIONAL STRUCTURE FIRST: implement project_groups in the spike now (not Phase 1): table project_groups (id, workspace_id, name, description), projects.group_id nullable FK, MCP tools create_group/assign_project_to_group/get_group_briefing, UI sidebar nesting. Groups are first-class: e.g. 'Zero2CEO' group containing zero2ceo-frontend + zero2ceo-backend projects; 'Arctx' group containing arctx-landing + arctx-platform. Group-level rollup briefing = key deliverable. (2) ROLES: four workspace-level tiers stored in workspace_members.role: Owner (all + billing + delete + role assignment), Admin (manage groups/projects/members/connections, no billing), Member (default working role: projects, tasks, context, docs, sessions), Viewer (read-only briefings/ledger/docs). Per-project overrides deferred. MCP connections inherit the authenticated human's role (no separate agent accounts). Clerk Organizations map 1:1 to Workspaces; Clerk org roles carry these role values. (3) OAUTH: Clerk as OAuth 2.1 authorization server for the MCP endpoint (dynamic client registration + PKCE + consent), spike route swaps static-bearer check for Clerk token verification + /.well-known metadata; DUAL AUTH transition (legacy bearer stays until Claude Code/Manus migrated, then revoked). Goal: Claude Desktop connects natively via Add Custom Connector with just the URL. This pulls Phase 1 auth forward because user needs personal production use ASAP.
• setup-sql · note · 2026-07-30 15:24
  Project seeded from setup.sql. First MCP session should see this entry.

Add context from the UI