# clairejerseyferrer/light-memory-challenge architecture

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

- Interactive diagram: https://gitdiagram.com/clairejerseyferrer/light-memory-challenge
- Repository: https://github.com/clairejerseyferrer/light-memory-challenge

## Overview

Light Memory Challenge is a physical memory game with an ESP32 device, a web interface, and a FastAPI backend. Players create and queue sessions, play on the device, then submit results for analysis and leaderboard ranking. The backend also exposes session status, device commands, and health information. The source excerpts show session and result handling, database helpers, and analysis; the README is empty, and firmware and browser implementation details were not sampled, so their connections are marked unverified where appropriate.

Main entry points: [`backend/main.py`](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/main.py) (FastAPI Service), [`backend/data_access.py`](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/data_access.py) (Session and Queue), [`web/index.html`](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/web/index.html) (Web Interface), [`backend/reliability.py`](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/reliability.py) (Database Reliability)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Game Clients"]
  node_web["Web Interface<br/>[index.html]"]
  node_firmware["ESP32 Game"]
end

subgraph group_api["Backend API"]
  node_api["FastAPI Service<br/>[main.py]"]
  node_session["Session and Queue<br/>[data_access.py]"]
  node_result["Result Handling<br/>[main.py]"]
end

subgraph group_gameplay["Gameplay and Analysis"]
  node_telemetry["Payload Normalization<br/>[telemetry.py]"]
  node_difficulty["Difficulty Events"]
  node_analysis["Performance Analysis"]
end

subgraph group_persistence["Persistence"]
  node_ranking["Results and Ranking<br/>[data_access.py]"]
  node_database[("Supabase Database")]
  node_schema["Database Schema<br/>[schema.sql]"]
end

subgraph group_operations["Reliability"]
  node_reliability["Database Reliability<br/>[reliability.py]"]
end

node_player(("Player"))

node_player -->|"uses"| node_web
node_web -.->|"requests"| node_api
node_firmware -.->|"sends game data"| node_api
node_api -->|"serves page"| node_web
node_api -->|"creates and reads sessions"| node_session
node_api -->|"accepts results"| node_result
node_result -.->|"normalizes payload"| node_telemetry
node_result -.->|"validates events"| node_difficulty
node_result -->|"analyzes performance"| node_analysis
node_api -->|"loads results"| node_ranking
node_session -->|"reads and writes"| node_database
node_ranking -->|"reads results"| node_database
node_api -->|"queries"| node_database
node_session -->|"imports error handling"| node_reliability
node_api -->|"checks database health"| node_reliability

click node_web "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/web/index.html"
click node_firmware "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/firmware/src/LightMemoryChallenge.ino"
click node_api "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/main.py"
click node_session "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/data_access.py"
click node_result "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/main.py"
click node_telemetry "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/telemetry.py"
click node_difficulty "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/difficulty_events.py"
click node_analysis "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/intelligent_system.py"
click node_ranking "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/data_access.py"
click node_schema "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/database/schema.sql"
click node_reliability "https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/reliability.py"

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_web,node_firmware toneBlue
class node_api,node_session,node_result toneAmber
class node_telemetry,node_difficulty,node_analysis toneMint
class node_ranking,node_database,node_schema toneRose
class node_reliability,node_player toneIndigo
```

## Components

### Game Clients

- [Web Interface](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/web/index.html): `web/index.html`
- [ESP32 Game](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/firmware/src/LightMemoryChallenge.ino): `firmware/src/LightMemoryChallenge.ino`

### Backend API

- [FastAPI Service](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/main.py): `backend/main.py`
- [Session and Queue](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/data_access.py): `backend/data_access.py`
- [Result Handling](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/main.py): `backend/main.py`

### Gameplay and Analysis

- [Payload Normalization](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/telemetry.py): `backend/telemetry.py`
- [Difficulty Events](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/difficulty_events.py): `backend/difficulty_events.py`
- [Performance Analysis](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/intelligent_system.py): `backend/intelligent_system.py`

### Persistence

- [Results and Ranking](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/data_access.py): `backend/data_access.py`
- **Supabase Database**
- [Database Schema](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/database/schema.sql): `database/schema.sql`

### Reliability

- [Database Reliability](https://github.com/clairejerseyferrer/light-memory-challenge/blob/main/backend/reliability.py): `backend/reliability.py`

### Other components

- **Player**

## Connections

- Player → Web Interface: uses
- Web Interface → FastAPI Service: requests
- ESP32 Game → FastAPI Service: sends game data
- FastAPI Service → Web Interface: serves page (evidence: `backend/main.py`)
- FastAPI Service → Session and Queue: creates and reads sessions (evidence: `backend/main.py`)
- FastAPI Service → Result Handling: accepts results (evidence: `backend/main.py`)
- Result Handling → Payload Normalization: normalizes payload (evidence: `backend/main.py`)
- Result Handling → Difficulty Events: validates events (evidence: `backend/main.py`)
- Result Handling → Performance Analysis: analyzes performance (evidence: `backend/main.py`)
- FastAPI Service → Results and Ranking: loads results (evidence: `backend/main.py`)
- Session and Queue → Supabase Database: reads and writes (evidence: `backend/data_access.py`)
- Results and Ranking → Supabase Database: reads results (evidence: `backend/data_access.py`)
- FastAPI Service → Supabase Database: queries (evidence: `backend/main.py`)
- Session and Queue → Database Reliability: imports error handling (evidence: `backend/data_access.py`)
- FastAPI Service → Database Reliability: checks database health (evidence: `backend/main.py`)
