# apoorv-xs/leveldevil architecture

> Architecture diagram of the GitHub repository apoorv-xs/leveldevil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apoorv-xs/leveldevil
- Repository: https://github.com/apoorv-xs/leveldevil

## Overview

This repository combines a documented 2.5D portfolio experience with a sales/workspace application and its API. The visitor path is the portfolio shell, synchronized visual/physics layers, and autonomous companion; API routes serve inquiry/application intake and authenticated owner/sales workflows. Portfolio links reflect README claims; API links reflect the shown source and SOURCE INDEX. Workspace modules are represented as a subsystem because their runtime wiring was not shown.

Main entry points: [`api/src/handlers.js`](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/handlers.js) (Request handlers), [`shell.js`](https://github.com/apoorv-xs/leveldevil/blob/main/shell.js) (DOM portfolio), [`api/src/errors.js`](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/errors.js) (API errors), [`portfolio_engine.js`](https://github.com/apoorv-xs/leveldevil/blob/main/portfolio_engine.js) (Portfolio engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portfolio["Portfolio runtime"]
  node_shell["DOM portfolio<br/>[shell.js]"]
  node_portfolio_engine["Portfolio engine"]
end

subgraph group_spatial["Spatial interaction"]
  node_three_engine["Three.js renderer<br/>[three_engine.js]"]
  node_player3d["BB-8 model<br/>[player_3d.js]"]
  node_physics["2D physics<br/>[kaboom.js]"]
  node_brain["Companion brain<br/>[system1_brain.js]"]
  node_holograms["Holographic graph"]
end

subgraph group_workspace["Sales workspace"]
  node_sales_app["Sales application<br/>[sales-app.js]"]
  node_workspace_app["Workspace app<br/>[app.js]"]
  node_prospect_tools["Prospect workflows"]
  node_deal_workflow["Deal closing<br/>[deal_closing.js]"]
  node_call_workflow["In-call workflow"]
end

subgraph group_api["API services"]
  node_api_routes["Function routes"]
  node_handlers["Request handlers<br/>[handlers.js]"]
  node_http["HTTP boundary<br/>[http.js]"]
  node_auth["Role authentication<br/>[auth.js]"]
  node_firebase["Firebase token verifier<br/>[firebase.js]"]
  node_services["Domain services<br/>[services.js]"]
  node_store[("In-memory repositories<br/>[store.js]")]
  node_ai["AI qualification<br/>[ai.js]"]
  node_prospects["Prospect data access<br/>[prospects.js]"]
  node_errors["API errors<br/>[errors.js]"]
  node_config["Firebase config<br/>[config.js]"]
end

node_visitor(("Visitor"))

node_visitor -->|"navigates"| node_shell
node_shell -->|"overlays 3D"| node_three_engine
node_shell -->|"overlays physics"| node_physics
node_shell -->|"coordinates descent"| node_portfolio_engine
node_portfolio_engine -->|"evaluates intent"| node_brain
node_portfolio_engine -->|"controls companion"| node_player3d
node_three_engine -->|"renders droid"| node_player3d
node_player3d -->|"projects graph"| node_holograms
node_api_routes -->|"runs boundary"| node_http
node_api_routes -->|"dispatches handler"| node_handlers
node_handlers -->|"validates and responds"| node_http
node_handlers -->|"guards access"| node_auth
node_handlers -->|"invokes services"| node_services
node_handlers -->|"qualifies"| node_ai
node_handlers -->|"reads prospects"| node_prospects
node_auth -->|"verifies token"| node_firebase
node_auth -->|"raises auth errors"| node_errors
node_firebase -->|"requires settings"| node_config
node_firebase -->|"raises service errors"| node_errors
node_services -->|"uses repositories"| node_store
node_services -->|"raises domain errors"| node_errors
node_prospects -->|"loads custom data"| node_prospect_tools
node_http -->|"formats failures"| node_errors

click node_shell "https://github.com/apoorv-xs/leveldevil/blob/main/shell.js"
click node_portfolio_engine "https://github.com/apoorv-xs/leveldevil/blob/main/portfolio_engine.js"
click node_three_engine "https://github.com/apoorv-xs/leveldevil/blob/main/three_engine.js"
click node_player3d "https://github.com/apoorv-xs/leveldevil/blob/main/player_3d.js"
click node_physics "https://github.com/apoorv-xs/leveldevil/blob/main/kaboom.js"
click node_brain "https://github.com/apoorv-xs/leveldevil/blob/main/system1_brain.js"
click node_holograms "https://github.com/apoorv-xs/leveldevil/blob/main/project_holograms.js"
click node_sales_app "https://github.com/apoorv-xs/leveldevil/blob/main/sales-app.js"
click node_workspace_app "https://github.com/apoorv-xs/leveldevil/blob/main/workspace/app.js"
click node_prospect_tools "https://github.com/apoorv-xs/leveldevil/blob/main/workspace/custom_prospects.js"
click node_deal_workflow "https://github.com/apoorv-xs/leveldevil/blob/main/workspace/deal_closing.js"
click node_call_workflow "https://github.com/apoorv-xs/leveldevil/blob/main/workspace/in_call_workflow.js"
click node_api_routes "https://github.com/apoorv-xs/leveldevil/tree/main/api/functions"
click node_handlers "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/handlers.js"
click node_http "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/http.js"
click node_auth "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/auth.js"
click node_firebase "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/firebase.js"
click node_services "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/services.js"
click node_store "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/store.js"
click node_ai "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/ai.js"
click node_prospects "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/prospects.js"
click node_errors "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/errors.js"
click node_config "https://github.com/apoorv-xs/leveldevil/blob/main/api/src/config.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_shell,node_portfolio_engine toneBlue
class node_three_engine,node_player3d,node_physics,node_brain,node_holograms toneAmber
class node_sales_app,node_workspace_app,node_prospect_tools,node_deal_workflow,node_call_workflow toneMint
class node_api_routes,node_handlers,node_http,node_auth,node_firebase,node_services,node_store,node_ai,node_prospects,node_errors,node_config toneRose
class node_visitor toneIndigo
```

## Components

### Portfolio runtime

- [DOM portfolio](https://github.com/apoorv-xs/leveldevil/blob/main/shell.js): `shell.js`
- [Portfolio engine](https://github.com/apoorv-xs/leveldevil/blob/main/portfolio_engine.js): `portfolio_engine.js`

### Spatial interaction

- [Three.js renderer](https://github.com/apoorv-xs/leveldevil/blob/main/three_engine.js): `three_engine.js`
- [BB-8 model](https://github.com/apoorv-xs/leveldevil/blob/main/player_3d.js): `player_3d.js`
- [2D physics](https://github.com/apoorv-xs/leveldevil/blob/main/kaboom.js): `kaboom.js`
- [Companion brain](https://github.com/apoorv-xs/leveldevil/blob/main/system1_brain.js): `system1_brain.js`
- [Holographic graph](https://github.com/apoorv-xs/leveldevil/blob/main/project_holograms.js): `project_holograms.js`

### Sales workspace

- [Sales application](https://github.com/apoorv-xs/leveldevil/blob/main/sales-app.js): `sales-app.js`
- [Workspace app](https://github.com/apoorv-xs/leveldevil/blob/main/workspace/app.js): `workspace/app.js`
- [Prospect workflows](https://github.com/apoorv-xs/leveldevil/blob/main/workspace/custom_prospects.js): `workspace/custom_prospects.js`
- [Deal closing](https://github.com/apoorv-xs/leveldevil/blob/main/workspace/deal_closing.js): `workspace/deal_closing.js`
- [In-call workflow](https://github.com/apoorv-xs/leveldevil/blob/main/workspace/in_call_workflow.js): `workspace/in_call_workflow.js`

### API services

- [Function routes](https://github.com/apoorv-xs/leveldevil/tree/main/api/functions): `api/functions`
- [Request handlers](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/handlers.js): `api/src/handlers.js`
- [HTTP boundary](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/http.js): `api/src/http.js`
- [Role authentication](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/auth.js): `api/src/auth.js`
- [Firebase token verifier](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/firebase.js): `api/src/firebase.js`
- [Domain services](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/services.js): `api/src/services.js`
- [In-memory repositories](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/store.js): `api/src/store.js`
- [AI qualification](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/ai.js): `api/src/ai.js`
- [Prospect data access](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/prospects.js): `api/src/prospects.js`
- [API errors](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/errors.js): `api/src/errors.js`
- [Firebase config](https://github.com/apoorv-xs/leveldevil/blob/main/api/src/config.js): `api/src/config.js`

### Other components

- **Visitor**

## Connections

- Visitor → DOM portfolio: navigates
- DOM portfolio → Three.js renderer: overlays 3D
- DOM portfolio → 2D physics: overlays physics
- DOM portfolio → Portfolio engine: coordinates descent
- Portfolio engine → Companion brain: evaluates intent
- Portfolio engine → BB-8 model: controls companion
- Three.js renderer → BB-8 model: renders droid
- BB-8 model → Holographic graph: projects graph
- Function routes → HTTP boundary: runs boundary (evidence: `api/functions/application/index.js`)
- Function routes → Request handlers: dispatches handler (evidence: `api/functions/application/index.js`)
- Request handlers → HTTP boundary: validates and responds (evidence: `api/src/handlers.js`)
- Request handlers → Role authentication: guards access (evidence: `api/src/handlers.js`)
- Request handlers → Domain services: invokes services (evidence: `api/src/handlers.js`)
- Request handlers → AI qualification: qualifies (evidence: `api/src/handlers.js`)
- Request handlers → Prospect data access: reads prospects (evidence: `api/src/handlers.js`)
- Role authentication → Firebase token verifier: verifies token (evidence: `api/src/auth.js`)
- Role authentication → API errors: raises auth errors (evidence: `api/src/auth.js`)
- Firebase token verifier → Firebase config: requires settings (evidence: `api/src/firebase.js`)
- Firebase token verifier → API errors: raises service errors (evidence: `api/src/firebase.js`)
- Domain services → In-memory repositories: uses repositories (evidence: `api/src/services.js`)
- Domain services → API errors: raises domain errors (evidence: `api/src/services.js`)
- Prospect data access → Prospect workflows: loads custom data (evidence: `api/src/prospects.js`)
- HTTP boundary → API errors: formats failures (evidence: `api/src/http.js`)
