# josephyt7/shadow-talk architecture

> Architecture diagram of the GitHub repository josephyt7/shadow-talk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josephyt7/shadow-talk
- Repository: https://github.com/josephyt7/shadow-talk

## Overview

ShadowTalk is a community chat application with an AI agent, membership-based Secret Society features, and a protected administration console. The principal workflow runs from a visitor using the React client to the Express/Socket.IO server, which handles chat and community events, with James providing AI responses. Separate branches cover email verification, society membership and chat, admin security and management, and visitor geolocation. Edges are limited to relationships supported by the excerpts, SOURCE INDEX references, or explicit file evidence; several UI and service implementations were not sampled.

Main entry points: [`server/james/agent.js`](https://github.com/josephyt7/shadow-talk/blob/main/server/james/agent.js) (James agent), [`server/admin/adminRoutes.js`](https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminRoutes.js) (Admin APIs), [`server/server.js`](https://github.com/josephyt7/shadow-talk/blob/main/server/server.js) (Chat server), [`client/src/App.jsx`](https://github.com/josephyt7/shadow-talk/blob/main/client/src/App.jsx) (Community app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Community client"]
  node_app["Community app<br/>[App.jsx]"]
  node_adminui["Admin console<br/>[AdminPanel.jsx]"]
  node_globe["Visitor globe<br/>[GeoGlobe3D.jsx]"]
  node_voiceui["Voice activator"]
end

subgraph group_runtime["Chat runtime"]
  node_server["Chat server<br/>[server.js]"]
  node_otp["Email verification<br/>[otpService.js]"]
end

subgraph group_james["James agent"]
  node_agent["James agent<br/>[agent.js]"]
  node_provider["AI provider<br/>[aiProvider.js]"]
  node_tools["Agent tools<br/>[tools.js]"]
  node_research["Web research<br/>[webResearch.js]"]
  node_memory["Agent memory<br/>[memory.js]"]
  node_moderation["Moderation<br/>[moderation.js]"]
  node_decision["Message decisions<br/>[decisionEngine.js]"]
  node_news["News service<br/>[newsService.js]"]
end

subgraph group_society["Society features"]
  node_member["Membership applications"]
  node_societyservice["Society service"]
  node_societychat["Society chat"]
end

subgraph group_admin["Administration"]
  node_adminroutes["Admin APIs<br/>[adminRoutes.js]"]
  node_auth["Admin sessions"]
  node_identity["Identity verification"]
  node_routeguard["Admin route protection"]
  node_voiceverify["Voice verification"]
  node_geo["Geolocation<br/>[geoService.js]"]
end

node_visitor(("Visitor"))

node_visitor -->|"uses"| node_app
node_app -.->|"chat events"| node_server
node_app -->|"opens"| node_adminui
node_app -->|"opens"| node_societychat
node_app -->|"renders"| node_voiceui
node_server -->|"verifies email"| node_otp
node_server -->|"handles applications"| node_member
node_server -->|"uses"| node_societyservice
node_server -->|"starts bot"| node_agent
node_server -->|"mounts routes"| node_adminroutes
node_agent -->|"requests completions"| node_provider
node_agent -->|"executes tools"| node_tools
node_agent -->|"uses"| node_research
node_agent -->|"records messages"| node_memory
node_agent -->|"uses"| node_moderation
node_agent -.->|"uses"| node_decision
node_agent -.->|"broadcasts news"| node_news
node_adminui -.->|"calls APIs"| node_adminroutes
node_adminroutes -->|"checks sessions"| node_auth
node_adminroutes -->|"verifies identity"| node_identity
node_adminroutes -->|"protects routes"| node_routeguard
node_adminroutes -->|"uses verification"| node_voiceverify
node_adminroutes -->|"loads visitor locations"| node_geo
node_adminroutes -->|"manages membership"| node_societyservice
node_adminui -->|"renders"| node_globe
node_globe -.->|"location data"| node_geo

click node_app "https://github.com/josephyt7/shadow-talk/blob/main/client/src/App.jsx"
click node_adminui "https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/admin/AdminPanel.jsx"
click node_globe "https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/admin/GeoGlobe3D.jsx"
click node_voiceui "https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/admin/HiddenVoiceActivator.jsx"
click node_server "https://github.com/josephyt7/shadow-talk/blob/main/server/server.js"
click node_otp "https://github.com/josephyt7/shadow-talk/blob/main/server/otpService.js"
click node_member "https://github.com/josephyt7/shadow-talk/blob/main/server/membershipService.js"
click node_societyservice "https://github.com/josephyt7/shadow-talk/blob/main/server/services/secretSocietyService.js"
click node_societychat "https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/society/SecretSocietyChat.jsx"
click node_agent "https://github.com/josephyt7/shadow-talk/blob/main/server/james/agent.js"
click node_provider "https://github.com/josephyt7/shadow-talk/blob/main/server/james/aiProvider.js"
click node_tools "https://github.com/josephyt7/shadow-talk/blob/main/server/james/tools.js"
click node_research "https://github.com/josephyt7/shadow-talk/blob/main/server/james/webResearch.js"
click node_memory "https://github.com/josephyt7/shadow-talk/blob/main/server/james/memory.js"
click node_moderation "https://github.com/josephyt7/shadow-talk/blob/main/server/james/moderation.js"
click node_decision "https://github.com/josephyt7/shadow-talk/blob/main/server/james/decisionEngine.js"
click node_news "https://github.com/josephyt7/shadow-talk/blob/main/server/james/newsService.js"
click node_adminroutes "https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminRoutes.js"
click node_auth "https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminAuthSession.js"
click node_identity "https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminIdentityVerification.js"
click node_routeguard "https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminRouteProtection.js"
click node_voiceverify "https://github.com/josephyt7/shadow-talk/blob/main/server/admin/voiceVerification.js"
click node_geo "https://github.com/josephyt7/shadow-talk/blob/main/server/services/geoService.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_adminui,node_globe,node_voiceui toneBlue
class node_server,node_otp toneAmber
class node_agent,node_provider,node_tools,node_research,node_memory,node_moderation,node_decision,node_news toneMint
class node_member,node_societyservice,node_societychat toneRose
class node_adminroutes,node_auth,node_identity,node_routeguard,node_voiceverify,node_geo,node_visitor toneIndigo
```

## Components

### Community client

- [Community app](https://github.com/josephyt7/shadow-talk/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Admin console](https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/admin/AdminPanel.jsx): `client/src/components/admin/AdminPanel.jsx`
- [Visitor globe](https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/admin/GeoGlobe3D.jsx): `client/src/components/admin/GeoGlobe3D.jsx`
- [Voice activator](https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/admin/HiddenVoiceActivator.jsx): `client/src/components/admin/HiddenVoiceActivator.jsx`

### Chat runtime

- [Chat server](https://github.com/josephyt7/shadow-talk/blob/main/server/server.js): `server/server.js`
- [Email verification](https://github.com/josephyt7/shadow-talk/blob/main/server/otpService.js): `server/otpService.js`

### James agent

- [James agent](https://github.com/josephyt7/shadow-talk/blob/main/server/james/agent.js): `server/james/agent.js`
- [AI provider](https://github.com/josephyt7/shadow-talk/blob/main/server/james/aiProvider.js): `server/james/aiProvider.js`
- [Agent tools](https://github.com/josephyt7/shadow-talk/blob/main/server/james/tools.js): `server/james/tools.js`
- [Web research](https://github.com/josephyt7/shadow-talk/blob/main/server/james/webResearch.js): `server/james/webResearch.js`
- [Agent memory](https://github.com/josephyt7/shadow-talk/blob/main/server/james/memory.js): `server/james/memory.js`
- [Moderation](https://github.com/josephyt7/shadow-talk/blob/main/server/james/moderation.js): `server/james/moderation.js`
- [Message decisions](https://github.com/josephyt7/shadow-talk/blob/main/server/james/decisionEngine.js): `server/james/decisionEngine.js`
- [News service](https://github.com/josephyt7/shadow-talk/blob/main/server/james/newsService.js): `server/james/newsService.js`

### Society features

- [Membership applications](https://github.com/josephyt7/shadow-talk/blob/main/server/membershipService.js): `server/membershipService.js`
- [Society service](https://github.com/josephyt7/shadow-talk/blob/main/server/services/secretSocietyService.js): `server/services/secretSocietyService.js`
- [Society chat](https://github.com/josephyt7/shadow-talk/blob/main/client/src/components/society/SecretSocietyChat.jsx): `client/src/components/society/SecretSocietyChat.jsx`

### Administration

- [Admin APIs](https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminRoutes.js): `server/admin/adminRoutes.js`
- [Admin sessions](https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminAuthSession.js): `server/admin/adminAuthSession.js`
- [Identity verification](https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminIdentityVerification.js): `server/admin/adminIdentityVerification.js`
- [Admin route protection](https://github.com/josephyt7/shadow-talk/blob/main/server/admin/adminRouteProtection.js): `server/admin/adminRouteProtection.js`
- [Voice verification](https://github.com/josephyt7/shadow-talk/blob/main/server/admin/voiceVerification.js): `server/admin/voiceVerification.js`
- [Geolocation](https://github.com/josephyt7/shadow-talk/blob/main/server/services/geoService.js): `server/services/geoService.js`

### Other components

- **Visitor**

## Connections

- Visitor → Community app: uses (evidence: `client/src/App.jsx`)
- Community app → Chat server: chat events
- Community app → Admin console: opens (evidence: `client/src/App.jsx`)
- Community app → Society chat: opens (evidence: `client/src/App.jsx`)
- Community app → Voice activator: renders (evidence: `client/src/App.jsx`)
- Chat server → Email verification: verifies email (evidence: `server/server.js`)
- Chat server → Membership applications: handles applications (evidence: `server/server.js`)
- Chat server → Society service: uses (evidence: `server/server.js`)
- Chat server → James agent: starts bot (evidence: `server/server.js`)
- Chat server → Admin APIs: mounts routes (evidence: `server/server.js`)
- James agent → AI provider: requests completions (evidence: `server/james/agent.js`)
- James agent → Agent tools: executes tools (evidence: `server/james/agent.js`)
- James agent → Web research: uses (evidence: `server/james/agent.js`)
- James agent → Agent memory: records messages (evidence: `server/james/agent.js`)
- James agent → Moderation: uses (evidence: `server/james/agent.js`)
- James agent → Message decisions: uses (evidence: `server/james/agent.js`)
- James agent → News service: broadcasts news
- Admin console → Admin APIs: calls APIs
- Admin APIs → Admin sessions: checks sessions (evidence: `server/admin/adminRoutes.js`)
- Admin APIs → Identity verification: verifies identity (evidence: `server/admin/adminRoutes.js`)
- Admin APIs → Admin route protection: protects routes (evidence: `server/admin/adminRoutes.js`)
- Admin APIs → Voice verification: uses verification (evidence: `server/admin/adminRoutes.js`)
- Admin APIs → Geolocation: loads visitor locations (evidence: `server/admin/adminRoutes.js`)
- Admin APIs → Society service: manages membership (evidence: `server/admin/adminRoutes.js`)
- Admin console → Visitor globe: renders (evidence: `client/src/components/admin/AdminPanel.jsx`)
- Visitor globe → Geolocation: location data