# therishabhpro/gapas-game-aesthetic-preference-analysis-system architecture

> Architecture diagram of the GitHub repository therishabhpro/gapas-game-aesthetic-preference-analysis-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system
- Repository: https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system

## Overview

GAPAS is a research dataset platform whose main workflow is to capture or upload gameplay screenshots, remove near-duplicates, persist session and image records, analyze images with a configurable VLM, validate annotations against one dataset schema, and export dataset rows. The graph distinguishes UI/API orchestration from capture, analysis, validation, storage, and export responsibilities. Some integration wiring is inferred only from documented capabilities or import references; unverified links are dashed, and unsampled implementation details are not asserted.

Main entry points: [`lib/vlm/analysis-pipeline.ts`](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/analysis-pipeline.ts) (VLM Analysis Pipeline), [`app/api/screenshots/route.ts`](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/screenshots/route.ts) (Screenshot API), [`lib/export/index.ts`](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/export/index.ts) (Export Query), [`lib/db/connection.ts`](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/connection.ts) (DB Connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Research UI"]
  node_sessionui["Session Workspace<br/>[page.tsx]"]
  node_uploadui["Folder Upload<br/>[UploadZone.tsx]"]
  node_sessionsapi["Session API<br/>[route.ts]"]
  node_sessiondetailapi["Session Detail API<br/>[route.ts]"]
end

subgraph group_capture["Capture Intake"]
  node_screensapi["Screenshot API<br/>[route.ts]"]
  node_capture["Live Capture<br/>[screen-capture.ts]"]
  node_dedupe["Duplicate Detection"]
  node_storage["Image Storage"]
end

subgraph group_analysis["Analysis and Schema"]
  node_analysisapi["Analysis API<br/>[route.ts]"]
  node_pipeline["VLM Analysis Pipeline"]
  node_provider["Provider Registry<br/>[index.ts]"]
  node_prompts["Prompt Builder<br/>[prompt-builder.ts]"]
  node_mockservice["Mock Analysis"]
  node_schema["Dataset Schema<br/>[dataset-schema.ts]"]
  node_validation["Response Validation"]
end

subgraph group_persistence["Persistence"]
  node_mongo[("MongoDB")]
  node_connection["DB Connection<br/>[connection.ts]"]
  node_sessionmodel[("Session Records<br/>[session.ts]")]
  node_screenshotmodel[("Screenshot Records<br/>[screenshot.ts]")]
  node_traitmodel[("Trait Records<br/>[trait.ts]")]
end

subgraph group_exports["Dataset Export"]
  node_exportapi["Export API<br/>[route.ts]"]
  node_exportquery["Export Query<br/>[index.ts]"]
  node_exporters["Format Exporters"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses capture"| node_sessionui
node_researcher -->|"uploads files"| node_uploadui
node_sessionui -.->|"starts capture"| node_capture
node_uploadui -->|"checks duplicates"| node_dedupe
node_sessionui -.->|"submits screenshots"| node_screensapi
node_screensapi -->|"checks hashes"| node_dedupe
node_screensapi -.->|"stores images"| node_storage
node_screensapi -->|"connects DB"| node_connection
node_screensapi -->|"reads and writes"| node_screenshotmodel
node_screensapi -->|"reads session"| node_sessionmodel
node_connection -->|"connects"| node_mongo
node_researcher -.->|"requests analysis"| node_analysisapi
node_analysisapi -->|"runs analysis"| node_pipeline
node_pipeline -->|"selects provider"| node_provider
node_pipeline -->|"builds prompts"| node_prompts
node_provider -->|"registers mock"| node_mockservice
node_pipeline -->|"validates response"| node_validation
node_validation -->|"derives fields"| node_schema
node_pipeline -->|"connects DB"| node_connection
node_pipeline -->|"updates status"| node_sessionmodel
node_pipeline -->|"reads and updates"| node_screenshotmodel
node_pipeline -->|"writes traits"| node_traitmodel
node_screenshotmodel -->|"builds analysis fields"| node_schema
node_researcher -.->|"requests export"| node_exportapi
node_exportapi -->|"queries rows"| node_exportquery
node_exportquery -->|"connects DB"| node_connection
node_exportquery -->|"reads traits"| node_traitmodel
node_exportquery -->|"dispatches format"| node_exporters
node_exportquery -->|"uses field order"| node_schema

click node_sessionui "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/session/%5Bid%5D/page.tsx"
click node_uploadui "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/components/UploadZone.tsx"
click node_sessionsapi "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/sessions/route.ts"
click node_sessiondetailapi "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/sessions/%5Bid%5D/route.ts"
click node_screensapi "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/screenshots/route.ts"
click node_capture "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/capture/screen-capture.ts"
click node_dedupe "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/capture/duplicate-detector.ts"
click node_storage "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/tree/main/lib/storage"
click node_analysisapi "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/analysis/route.ts"
click node_pipeline "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/analysis-pipeline.ts"
click node_provider "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/index.ts"
click node_prompts "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/prompt-builder.ts"
click node_mockservice "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/mock-analysis-service.ts"
click node_schema "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/schema/dataset-schema.ts"
click node_validation "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/validation/schema-validator.ts"
click node_connection "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/connection.ts"
click node_sessionmodel "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/models/session.ts"
click node_screenshotmodel "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/models/screenshot.ts"
click node_traitmodel "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/models/trait.ts"
click node_exportapi "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/export/route.ts"
click node_exportquery "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/export/index.ts"
click node_exporters "https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/tree/main/lib/export"

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_sessionui,node_uploadui,node_sessionsapi,node_sessiondetailapi toneBlue
class node_screensapi,node_capture,node_dedupe,node_storage toneAmber
class node_analysisapi,node_pipeline,node_provider,node_prompts,node_mockservice,node_schema,node_validation toneMint
class node_mongo,node_connection,node_sessionmodel,node_screenshotmodel,node_traitmodel toneRose
class node_exportapi,node_exportquery,node_exporters,node_researcher toneIndigo
```

## Components

### Research UI

- [Session Workspace](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/session/%5Bid%5D/page.tsx): `app/session/[id]/page.tsx`
- [Folder Upload](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/components/UploadZone.tsx): `components/UploadZone.tsx`
- [Session API](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/sessions/route.ts): `app/api/sessions/route.ts`
- [Session Detail API](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/sessions/%5Bid%5D/route.ts): `app/api/sessions/[id]/route.ts`

### Capture Intake

- [Screenshot API](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/screenshots/route.ts): `app/api/screenshots/route.ts`
- [Live Capture](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/capture/screen-capture.ts): `lib/capture/screen-capture.ts`
- [Duplicate Detection](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/capture/duplicate-detector.ts): `lib/capture/duplicate-detector.ts`
- [Image Storage](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/tree/main/lib/storage): `lib/storage`

### Analysis and Schema

- [Analysis API](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/analysis/route.ts): `app/api/analysis/route.ts`
- [VLM Analysis Pipeline](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/analysis-pipeline.ts): `lib/vlm/analysis-pipeline.ts`
- [Provider Registry](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/index.ts): `lib/vlm/index.ts`
- [Prompt Builder](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/prompt-builder.ts): `lib/vlm/prompt-builder.ts`
- [Mock Analysis](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/vlm/mock-analysis-service.ts): `lib/vlm/mock-analysis-service.ts`
- [Dataset Schema](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/schema/dataset-schema.ts): `lib/schema/dataset-schema.ts`
- [Response Validation](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/validation/schema-validator.ts): `lib/validation/schema-validator.ts`

### Persistence

- **MongoDB**
- [DB Connection](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/connection.ts): `lib/db/connection.ts`
- [Session Records](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/models/session.ts): `lib/db/models/session.ts`
- [Screenshot Records](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/models/screenshot.ts): `lib/db/models/screenshot.ts`
- [Trait Records](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/db/models/trait.ts): `lib/db/models/trait.ts`

### Dataset Export

- [Export API](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/app/api/export/route.ts): `app/api/export/route.ts`
- [Export Query](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/blob/main/lib/export/index.ts): `lib/export/index.ts`
- [Format Exporters](https://github.com/therishabhpro/gapas-game-aesthetic-preference-analysis-system/tree/main/lib/export): `lib/export`

### Other components

- **Researcher**

## Connections

- Researcher → Session Workspace: uses capture (evidence: `README.md`)
- Researcher → Folder Upload: uploads files (evidence: `README.md`)
- Session Workspace → Live Capture: starts capture (evidence: `app/session/[id]/page.tsx`)
- Folder Upload → Duplicate Detection: checks duplicates (evidence: `components/UploadZone.tsx`)
- Session Workspace → Screenshot API: submits screenshots
- Screenshot API → Duplicate Detection: checks hashes (evidence: `app/api/screenshots/route.ts`)
- Screenshot API → Image Storage: stores images (evidence: `app/api/screenshots/route.ts`)
- Screenshot API → DB Connection: connects DB (evidence: `app/api/screenshots/route.ts`)
- Screenshot API → Screenshot Records: reads and writes (evidence: `app/api/screenshots/route.ts`)
- Screenshot API → Session Records: reads session (evidence: `app/api/screenshots/route.ts`)
- DB Connection → MongoDB: connects (evidence: `lib/db/connection.ts`)
- Researcher → Analysis API: requests analysis
- Analysis API → VLM Analysis Pipeline: runs analysis (evidence: `app/api/analysis/route.ts`)
- VLM Analysis Pipeline → Provider Registry: selects provider (evidence: `lib/vlm/analysis-pipeline.ts`)
- VLM Analysis Pipeline → Prompt Builder: builds prompts (evidence: `lib/vlm/analysis-pipeline.ts`)
- Provider Registry → Mock Analysis: registers mock (evidence: `lib/vlm/index.ts`)
- VLM Analysis Pipeline → Response Validation: validates response (evidence: `lib/vlm/analysis-pipeline.ts`)
- Response Validation → Dataset Schema: derives fields
- VLM Analysis Pipeline → DB Connection: connects DB (evidence: `lib/vlm/analysis-pipeline.ts`)
- VLM Analysis Pipeline → Session Records: updates status (evidence: `lib/vlm/analysis-pipeline.ts`)
- VLM Analysis Pipeline → Screenshot Records: reads and updates (evidence: `lib/vlm/analysis-pipeline.ts`)
- VLM Analysis Pipeline → Trait Records: writes traits (evidence: `lib/vlm/analysis-pipeline.ts`)
- Screenshot Records → Dataset Schema: builds analysis fields (evidence: `lib/db/models/screenshot.ts`)
- Researcher → Export API: requests export
- Export API → Export Query: queries rows (evidence: `app/api/export/route.ts`)
- Export Query → DB Connection: connects DB (evidence: `lib/export/index.ts`)
- Export Query → Trait Records: reads traits (evidence: `lib/export/index.ts`)
- Export Query → Format Exporters: dispatches format (evidence: `lib/export/index.ts`)
- Export Query → Dataset Schema: uses field order (evidence: `lib/export/index.ts`)
