# energyshifter8/conflict-detect architecture

> Architecture diagram of the GitHub repository energyshifter8/conflict-detect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/energyshifter8/conflict-detect
- Repository: https://github.com/energyshifter8/conflict-detect

## Overview

TeamPresence is a VS Code extension plus a Node server for sharing repository-relative editing presence and warning about potential conflicts. The main workflow is workspace consent and repository discovery, local edit tracking, WebSocket presence exchange, authoritative room state/conflict calculation, and editor/sidebar/status notifications. The shared package defines the wire contract and range/repository helpers. The README documents token administration, simulator, health endpoint, and security behavior; source excerpts show server wiring and core client/service behavior, but not every UI or gateway handler, so some documented links remain unverified.

Main entry points: [`packages/extension/src/repoSession.ts`](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/repoSession.ts) (Repository session), [`packages/server/src/ws/gateway.ts`](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/ws/gateway.ts) (WebSocket gateway), [`packages/extension/src/controller.ts`](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/controller.ts) (Workspace controller), [`packages/extension/src/presence/tracker.ts`](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/presence/tracker.ts) (Presence tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["VS Code extension"]
  node_controller["Workspace controller<br/>[controller.ts]"]
  node_git["Git metadata<br/>[gitInfo.ts]"]
  node_ignore["Ignore matcher<br/>[ignore.ts]"]
  node_tracker["Presence tracker<br/>[tracker.ts]"]
  node_repo_session["Repository session<br/>[repoSession.ts]"]
  node_client["WebSocket client<br/>[client.ts]"]
  node_team_state["Team state<br/>[teamState.ts]"]
  node_decorations["Inline decorations<br/>[decorations.ts]"]
  node_notifications["Conflict notifications<br/>[notifications.ts]"]
  node_notification_policy["Notification policy"]
  node_status_tree["Status and team views<br/>[statusBar.ts]"]
end

subgraph group_server["Presence server"]
  node_gateway["WebSocket gateway<br/>[gateway.ts]"]
  node_presence_service["Room presence service<br/>[service.ts]"]
  node_conflict_detection["Conflict detection<br/>[detect.ts]"]
  node_presence_store[("Presence store<br/>[memoryStore.ts]")]
  node_http_health["Health endpoint<br/>[http.ts]"]
  node_simulator["Presence simulator<br/>[simulate.ts]"]
end

subgraph group_shared["Shared protocol"]
  node_protocol["Wire protocol<br/>[protocol.ts]"]
  node_repo_id["Repository identity<br/>[repoId.ts]"]
end

subgraph group_identity["Identity and security"]
  node_authenticator["Token authentication<br/>[authenticator.ts]"]
  node_token_registry["Token registry<br/>[tokenRegistry.ts]"]
  node_token_admin["Token administration<br/>[tokens.ts]"]
  node_ip_protection["IP protection"]
  node_ip_resolution["Client IP resolution<br/>[clientIp.ts]"]
end

node_developer(("VS Code user"))

node_developer -->|"starts extension"| node_controller
node_controller -->|"discovers repositories"| node_git
node_controller -->|"configures ignores"| node_ignore
node_controller -.->|"starts sessions"| node_repo_session
node_repo_session -->|"reads branch"| node_git
node_repo_session -->|"starts tracking"| node_tracker
node_repo_session -->|"opens connection"| node_client
node_repo_session -->|"owns state"| node_team_state
node_repo_session -->|"creates decorations"| node_decorations
node_repo_session -->|"creates notifier"| node_notifications
node_tracker -->|"checks paths"| node_ignore
node_tracker -->|"uses repo metadata"| node_git
node_tracker -->|"publishes presence"| node_client
node_client -->|"exchanges messages"| node_gateway
node_client -->|"validates messages"| node_protocol
node_gateway -->|"authenticates joins"| node_authenticator
node_authenticator -->|"verifies tokens"| node_token_registry
node_token_admin -->|"manages tokens"| node_token_registry
node_gateway -->|"checks failed sign-ins"| node_ip_protection
node_gateway -->|"resolves client IP"| node_ip_resolution
node_gateway -->|"dispatches room actions"| node_presence_service
node_presence_service -->|"reads and writes sessions"| node_presence_store
node_presence_service -->|"computes conflicts"| node_conflict_detection
node_presence_service -->|"builds wire state"| node_protocol
node_gateway -->|"parses client messages"| node_protocol
node_team_state -->|"supplies peer state"| node_decorations
node_team_state -.->|"supplies team state"| node_notifications
node_notifications -.->|"checks notification rules"| node_notification_policy
node_team_state -->|"renders team status"| node_status_tree
node_controller -->|"sets policy"| node_notification_policy
node_repo_id -->|"normalizes room identity"| node_controller
node_simulator -.->|"simulates clients"| node_gateway
node_developer -->|"views team activity"| node_status_tree
node_developer -->|"sees file markers"| node_decorations
node_developer -->|"receives warnings"| node_notifications
node_developer -->|"checks health"| node_http_health

click node_controller "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/controller.ts"
click node_git "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/git/gitInfo.ts"
click node_ignore "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/presence/ignore.ts"
click node_tracker "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/presence/tracker.ts"
click node_repo_session "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/repoSession.ts"
click node_client "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/net/client.ts"
click node_team_state "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/state/teamState.ts"
click node_decorations "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/decorations.ts"
click node_notifications "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/notifications.ts"
click node_notification_policy "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/notificationPolicy.ts"
click node_status_tree "https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/statusBar.ts"
click node_gateway "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/ws/gateway.ts"
click node_authenticator "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/auth/authenticator.ts"
click node_token_registry "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/auth/tokenRegistry.ts"
click node_token_admin "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/cli/tokens.ts"
click node_ip_protection "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/security/authFailureLimiter.ts"
click node_ip_resolution "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/net/clientIp.ts"
click node_presence_service "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/presence/service.ts"
click node_conflict_detection "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/conflicts/detect.ts"
click node_presence_store "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/presence/memoryStore.ts"
click node_http_health "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/http.ts"
click node_simulator "https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/simulate.ts"
click node_protocol "https://github.com/energyshifter8/conflict-detect/blob/master/packages/shared/src/protocol.ts"
click node_repo_id "https://github.com/energyshifter8/conflict-detect/blob/master/packages/shared/src/repoId.ts"

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_controller,node_git,node_ignore,node_tracker,node_repo_session,node_client,node_team_state,node_decorations,node_notifications,node_notification_policy,node_status_tree,node_developer toneBlue
class node_gateway,node_presence_service,node_conflict_detection,node_presence_store,node_http_health,node_simulator toneAmber
class node_protocol,node_repo_id toneMint
class node_authenticator,node_token_registry,node_token_admin,node_ip_protection,node_ip_resolution toneRose
```

## Components

### VS Code extension

- [Workspace controller](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/controller.ts): `packages/extension/src/controller.ts`
- [Git metadata](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/git/gitInfo.ts): `packages/extension/src/git/gitInfo.ts`
- [Ignore matcher](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/presence/ignore.ts): `packages/extension/src/presence/ignore.ts`
- [Presence tracker](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/presence/tracker.ts): `packages/extension/src/presence/tracker.ts`
- [Repository session](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/repoSession.ts): `packages/extension/src/repoSession.ts`
- [WebSocket client](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/net/client.ts): `packages/extension/src/net/client.ts`
- [Team state](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/state/teamState.ts): `packages/extension/src/state/teamState.ts`
- [Inline decorations](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/decorations.ts): `packages/extension/src/ui/decorations.ts`
- [Conflict notifications](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/notifications.ts): `packages/extension/src/ui/notifications.ts`
- [Notification policy](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/notificationPolicy.ts): `packages/extension/src/ui/notificationPolicy.ts`
- [Status and team views](https://github.com/energyshifter8/conflict-detect/blob/master/packages/extension/src/ui/statusBar.ts): `packages/extension/src/ui/statusBar.ts`

### Presence server

- [WebSocket gateway](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/ws/gateway.ts): `packages/server/src/ws/gateway.ts`
- [Room presence service](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/presence/service.ts): `packages/server/src/presence/service.ts`
- [Conflict detection](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/conflicts/detect.ts): `packages/server/src/conflicts/detect.ts`
- [Presence store](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/presence/memoryStore.ts): `packages/server/src/presence/memoryStore.ts`
- [Health endpoint](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/http.ts): `packages/server/src/http.ts`
- [Presence simulator](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/simulate.ts): `packages/server/src/simulate.ts`

### Shared protocol

- [Wire protocol](https://github.com/energyshifter8/conflict-detect/blob/master/packages/shared/src/protocol.ts): `packages/shared/src/protocol.ts`
- [Repository identity](https://github.com/energyshifter8/conflict-detect/blob/master/packages/shared/src/repoId.ts): `packages/shared/src/repoId.ts`

### Identity and security

- [Token authentication](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/auth/authenticator.ts): `packages/server/src/auth/authenticator.ts`
- [Token registry](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/auth/tokenRegistry.ts): `packages/server/src/auth/tokenRegistry.ts`
- [Token administration](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/cli/tokens.ts): `packages/server/src/cli/tokens.ts`
- [IP protection](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/security/authFailureLimiter.ts): `packages/server/src/security/authFailureLimiter.ts`
- [Client IP resolution](https://github.com/energyshifter8/conflict-detect/blob/master/packages/server/src/net/clientIp.ts): `packages/server/src/net/clientIp.ts`

### Other components

- **VS Code user**

## Connections

- VS Code user → Workspace controller: starts extension (evidence: `README.md`)
- Workspace controller → Git metadata: discovers repositories (evidence: `packages/extension/src/controller.ts`)
- Workspace controller → Ignore matcher: configures ignores (evidence: `packages/extension/src/controller.ts`)
- Workspace controller → Repository session: starts sessions (evidence: `packages/extension/src/controller.ts`)
- Repository session → Git metadata: reads branch (evidence: `packages/extension/src/repoSession.ts`)
- Repository session → Presence tracker: starts tracking (evidence: `packages/extension/src/repoSession.ts`)
- Repository session → WebSocket client: opens connection (evidence: `packages/extension/src/repoSession.ts`)
- Repository session → Team state: owns state (evidence: `packages/extension/src/repoSession.ts`)
- Repository session → Inline decorations: creates decorations (evidence: `packages/extension/src/repoSession.ts`)
- Repository session → Conflict notifications: creates notifier (evidence: `packages/extension/src/repoSession.ts`)
- Presence tracker → Ignore matcher: checks paths (evidence: `packages/extension/src/presence/tracker.ts`)
- Presence tracker → Git metadata: uses repo metadata (evidence: `packages/extension/src/presence/tracker.ts`)
- Presence tracker → WebSocket client: publishes presence (evidence: `packages/extension/src/repoSession.ts`)
- WebSocket client → WebSocket gateway: exchanges messages (evidence: `README.md`)
- WebSocket client → Wire protocol: validates messages (evidence: `packages/extension/src/net/client.ts`)
- WebSocket gateway → Token authentication: authenticates joins (evidence: `packages/server/src/ws/gateway.ts`)
- Token authentication → Token registry: verifies tokens (evidence: `packages/server/src/auth/authenticator.ts`)
- Token administration → Token registry: manages tokens (evidence: `packages/server/src/cli/tokens.ts`)
- WebSocket gateway → IP protection: checks failed sign-ins (evidence: `packages/server/src/ws/gateway.ts`)
- WebSocket gateway → Client IP resolution: resolves client IP (evidence: `packages/server/src/ws/gateway.ts`)
- WebSocket gateway → Room presence service: dispatches room actions (evidence: `packages/server/src/ws/gateway.ts`)
- Room presence service → Presence store: reads and writes sessions (evidence: `packages/server/src/presence/service.ts`)
- Room presence service → Conflict detection: computes conflicts (evidence: `packages/server/src/presence/service.ts`)
- Room presence service → Wire protocol: builds wire state (evidence: `packages/server/src/presence/service.ts`)
- WebSocket gateway → Wire protocol: parses client messages (evidence: `packages/server/src/ws/gateway.ts`)
- Team state → Inline decorations: supplies peer state (evidence: `packages/extension/src/ui/decorations.ts`)
- Team state → Conflict notifications: supplies team state
- Conflict notifications → Notification policy: checks notification rules
- Team state → Status and team views: renders team status (evidence: `packages/extension/src/ui/treeView.ts`)
- Workspace controller → Notification policy: sets policy (evidence: `packages/extension/src/controller.ts`)
- Repository identity → Workspace controller: normalizes room identity (evidence: `packages/extension/src/controller.ts`)
- Presence simulator → WebSocket gateway: simulates clients (evidence: `README.md`)
- VS Code user → Status and team views: views team activity (evidence: `README.md`)
- VS Code user → Inline decorations: sees file markers (evidence: `README.md`)
- VS Code user → Conflict notifications: receives warnings (evidence: `README.md`)
- VS Code user → Health endpoint: checks health (evidence: `README.md`)
