# brightwav3/agent-face architecture

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

- Interactive diagram: https://gitdiagram.com/brightwav3/agent-face
- Repository: https://github.com/brightwav3/agent-face

## Overview

Agent Face is a dependency-free JavaScript library for rendering expressive, animated SVG faces. The main workflow is: an integrator creates a face in a container, configures its shape, state and appearance, then updates it through the API; the library tracks gaze and animation and renders the result. The sampled source shows DOM setup, pointer sharing, visibility handling and rendering in one runtime file, so these are internal responsibilities rather than separate modules. The README documents additional capabilities that the excerpts do not show in detail.

Main entry points: [`src/agent-face.src.js`](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js) (AgentFace runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Face API"]
  node_library["AgentFace runtime<br/>[agent-face.src.js]"]
end

subgraph group_motion["Interaction and motion"]
  node_shared_pointer["Shared pointer<br/>[agent-face.src.js]"]
  node_visibility["Visibility and theme<br/>[agent-face.src.js]"]
  node_animation["Face animation<br/>[agent-face.src.js]"]
end

subgraph group_render["SVG rendering"]
  node_svg_setup["SVG setup<br/>[agent-face.src.js]"]
  node_svg_render["SVG rendering<br/>[agent-face.src.js]"]
end

node_integrator(("Integrator"))

node_integrator -->|"creates and updates"| node_library
node_library -->|"builds DOM"| node_svg_setup
node_library -->|"binds when tracking"| node_shared_pointer
node_library -->|"observes face and theme"| node_visibility
node_animation -->|"renders each frame"| node_svg_render
node_shared_pointer -->|"kicks live faces"| node_animation
node_visibility -->|"kicks when visible"| node_animation

click node_library "https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js"
click node_shared_pointer "https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js"
click node_visibility "https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js"
click node_animation "https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js"
click node_svg_setup "https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js"
click node_svg_render "https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.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_library toneBlue
class node_shared_pointer,node_visibility,node_animation toneAmber
class node_svg_setup,node_svg_render toneMint
class node_integrator toneIndigo
```

## Components

### Face API

- [AgentFace runtime](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js): `src/agent-face.src.js`

### Interaction and motion

- [Shared pointer](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js): `src/agent-face.src.js`
- [Visibility and theme](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js): `src/agent-face.src.js`
- [Face animation](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js): `src/agent-face.src.js`

### SVG rendering

- [SVG setup](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js): `src/agent-face.src.js`
- [SVG rendering](https://github.com/brightwav3/agent-face/blob/main/src/agent-face.src.js): `src/agent-face.src.js`

### Other components

- **Integrator**

## Connections

- Integrator → AgentFace runtime: creates and updates (evidence: `README.md`)
- AgentFace runtime → SVG setup: builds DOM (evidence: `src/agent-face.src.js`)
- AgentFace runtime → Shared pointer: binds when tracking (evidence: `src/agent-face.src.js`)
- AgentFace runtime → Visibility and theme: observes face and theme (evidence: `src/agent-face.src.js`)
- Face animation → SVG rendering: renders each frame (evidence: `src/agent-face.src.js`)
- Shared pointer → Face animation: kicks live faces (evidence: `src/agent-face.src.js`)
- Visibility and theme → Face animation: kicks when visible (evidence: `src/agent-face.src.js`)
