Project Structure

Genie Helper is built on AnythingLLM with custom extensions. This guide covers the codebase organization, key directories, and file structure to help you navigate the project effectively.

Directory Overview

agentx/
├── scripts/          MCP servers + CLI utilities
├── server/           AnythingLLM backend (Express + Prisma)
├── dashboard/        React SPA (Vite + Tailwind + React Router v6)
├── media-worker/     BullMQ media processing worker
├── cms/              Directus extensions
├── storage/          AnythingLLM persistent storage + MCP config
├── docs/nginx/       Nginx vhost configs (Plesk reference)
└── .claude/sessions/ Development session logs

Core Server (`server/`)

The server directory contains all backend logic built on top of AnythingLLM’s Express server.

API Endpoints (`server/endpoints/api/`)

File	Route	Purpose
`genieChat.js`	`/api/genie/stream-chat`	Content gate + node RAG injection + SSE proxy to AnythingLLM
`credentials.js`	`/api/credentials/*`	AES-256-GCM encrypted platform credential storage/retrieval
`queue.js`	`/api/queue/*`	BullMQ job enqueue + stats API
`captions.js`	`/api/captions/generate`	AI caption generation endpoint
`register.js`	`/api/register`	Invite-gated registration proxy
`impersonate.js`	`/api/impersonate/*`	Admin impersonation (session swap)
`rbacSync.js`	`/api/rbac-sync/*`	Directus ↔ AnythingLLM user sync
`onboarding.js`	`/api/onboarding`	State machine GET/PATCH + zip upload webhook
`userProxy.js`	`/api/users/*`	User profile + file upload admin-token proxy
`usage.js`	`/api/usage/*`	Plan usage tracking

Utilities (`server/utils/`)

Directory/File	Purpose
`actionRunner/`	Action flow executor (see Custom Actions)
`credentialsCrypto.js`	AES-256-GCM encryption for platform credentials
`boot/`	MCP server auto-boot on AnythingLLM startup
`nodeRag.js`	Node RAG pipeline — top-15 weighted persona nodes, 5-min cache
`cache/`	Extract cache and taxonomy cache implementations
`actionBus.js`	BullMQ ActionBus interface

Example: Credential Encryption Platform credentials are encrypted server-side before storage:

// server/utils/credentialsCrypto.js
const { encryptJSON, decryptJSON } = require('./utils/credentialsCrypto');

// Encrypt credentials
const encrypted = encryptJSON({ username: 'user', password: 'pass' });
// Returns: { enc: "v1:iv:tag:ciphertext" }

// Decrypt credentials
const decrypted = decryptJSON(encrypted);
// Returns: { username: 'user', password: 'pass' }

Requires CREDENTIALS_ENC_KEY_B64 environment variable (base64 of 32 bytes).

MCP Servers (`scripts/`)

MCP (Model Context Protocol) servers expose external services as tools to the AI agent.

File	Tools	Purpose
`directus-mcp-server.mjs`	17 tools	CRUD collections, trigger flows, manage users/files
`ollama-mcp-server.mjs`	3 tools	generate, chat, list-models
`stagehand-mcp-server.mjs`	9 tools	Browser automation (sessions, navigate, act, extract, cookies, screenshot)

See Extending MCP for details on adding new tools.

Dashboard (`dashboard/`)

React 18 SPA served from dashboard/dist/ at geniehelper.com/.

Key Files

File	Purpose
`src/utils/api.js`	Axios client — all Directus + AnythingLLM calls
`src/utils/crypto.js`	Client-side encryption utilities
`src/components/AgentWidget/`	Custom chat popup (replaces embed widget)
`src/components/Brand/ThemeApplier.jsx`	CSS custom property injector from brand settings
`src/components/Layout/Sidebar.jsx`	Nav sidebar + persona theme loader
`src/pages/*`	Route pages (Dashboard, MediaLibrary, Settings, etc.)

Routes

Public routes:

/ — Home
/pricing, /about, /register, /login

Authenticated routes:

/app/dashboard — Main dashboard
/app/media — Media library
/app/calendar — Content calendar
/app/fans — Fan management
/app/analytics — Performance analytics
/app/platforms — Platform connections
/app/settings — User settings

Admin routes:

/admin — Directus + AnythingLLM iframes
/view-as — User impersonation

Build Process

cd dashboard
npm run build
# Output: dashboard/dist/

Served by pm2 with serve dashboard/dist/ (pm2 name: genie-dashboard).

Media Worker (`media-worker/`)

BullMQ consumer that processes background jobs:

scrape_profile — Stagehand OF login + data extraction
publish_post — Stagehand-based cross-platform posting
apply_watermark — ImageMagick watermarking
create_teaser — FFmpeg video preview generation
post_scheduler — Polls scheduled_posts every 60s

Runs as pm2 process (name: media-worker).

Storage (`storage/`)

AnythingLLM persistent data:

plugins/anythingllm_mcp_servers.json — MCP server configuration (see Extending MCP)
Document vectors, user data, workspaces

Agent & AI

server/utils/nodeRag.js — getOnboardingState() + getNodeContext()
Nodes/Universe/taxonomy_graph.json — 3,205-node taxonomy graph
Nodes/User/ — Per-user persona node storage

Planning & Tracking

.claude/todos — Phase backlog with agent assignments
.claude/sessions/ — EOD session logs
docs/nginx/ — Nginx config references

Next Steps

Custom Actions

Create custom Action Runner flows

Extending MCP

Add new MCP tools and servers

Usage

Administration

Development

Directory Overview

Core Server (`server/`)

API Endpoints (`server/endpoints/api/`)

Utilities (`server/utils/`)

MCP Servers (`scripts/`)

Dashboard (`dashboard/`)

Key Files

Routes

Build Process

Media Worker (`media-worker/`)

Storage (`storage/`)

Agent & AI

Planning & Tracking

Next Steps

Custom Actions

Extending MCP

​Directory Overview

​Core Server (server/)

​API Endpoints (server/endpoints/api/)

​Utilities (server/utils/)

​MCP Servers (scripts/)

​Dashboard (dashboard/)

​Key Files

​Routes

​Build Process

​Media Worker (media-worker/)

​Storage (storage/)

​Related Files Reference

​Agent & AI

​Planning & Tracking

​Next Steps

Custom Actions

Extending MCP

Directory Overview

Core Server (`server/`)

API Endpoints (`server/endpoints/api/`)

Utilities (`server/utils/`)

MCP Servers (`scripts/`)

Dashboard (`dashboard/`)

Key Files

Routes

Build Process

Media Worker (`media-worker/`)

Storage (`storage/`)

Related Files Reference

Agent & AI

Planning & Tracking

Next Steps