# eswarr11/image-testcase-generator architecture

> Architecture diagram of the GitHub repository eswarr11/image-testcase-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eswarr11/image-testcase-generator
- Repository: https://github.com/eswarr11/image-testcase-generator

## Overview

#### Purpose and entry points
This monorepo generates Jira-ready test cases from Confluence pages, Figma designs, uploaded images, and an optional focus prompt. It has a React/Vite client and TypeScript/Express API.

- API process and app composition: `backend/src/main.ts`, `backend/src/app.ts`
- Client bootstrap and application shell: `frontend/src/main.tsx`, `frontend/src/App.tsx`
- Deployment adapter/configuration: `api/index.js`, `vercel.json`

#### Backend HTTP composition
Express assembles cross-cutting security, CORS, request tracing, error translation, and feature routes before serving requests. Modules are organized around controller → service → DTO boundaries.

- App and route aggregation: `backend/src/app.ts`, `backend/src/modules/index.ts`
- Cross-cutting failure/trace boundary: `backend/src/middleware/errorHandler.middleware.ts`, `backend/src/logger/trace.middleware.ts`
- Health endpoint: `backend/src/modules/health/health.routes.ts`

#### Session vault and secret boundary
The browser holds only an httpOnly session-cookie identifier. Session credentials/API keys are persisted server-side and encrypted before storage, keeping OpenAI, Atlassian, and Figma credentials out of client application state.

- Cookie/session route boundary: `backend/src/modules/session/middleware/sessionCookie.ts`, `backend/src/modules/session/session.routes.ts`
- Session orchestration and persistence: `backend/src/modules/session/core/services/session.service.ts`, `backend/src/modules/session/core/repositories/session.repository.ts`
- Encryption and database client: `backend/src/db/crypto.ts`, `backend/src/db/client.ts`

#### Source acquisition and caching
The sources module accepts Confluence/Figma URLs, authenticates against upstream services, extracts usable text or image/design content, and caches upstream responses in SQLite to reduce repeat calls. URL parsing and Figma fetching are isolated utility boundaries.

- Source HTTP/controller layer: `backend/src/modules/sources/sources.routes.ts`, `backend/src/modules/sources/core/controllers/sources.controller.ts`
- Upstream integrations: `backend/src/modules/sources/core/services/confluence.service.ts`, `backend/src/modules/sources/core/services/figma.service.ts`, `backend/src/modules/sources/core/services/atlassian-auth.service.ts`
- Cache and extraction utilities: `backend/src/db/source-cache.ts`, `backend/src/utils/textExtract.ts`, `backend/src/utils/figmaFetch.ts`

#### Test-case generation pipeline
Generation is graph-orchestrated: submitted requirements, source content, images, and prompt constraints are processed into structured GPT-4o output, then evaluated for coverage. The backend owns model invocation and output structuring rather than exposing provider credentials to the frontend.

- Request API and DTO: `backend/src/modules/generate/generate.routes.ts`, `backend/src/modules/generate/dto/generate.dto.ts`
- Graph/control flow: `backend/src/modules/generate/core/graph/orchestrator.graph.ts`, `backend/src/modules/generate/core/graph/generate.graph.ts`
- Core stages: `backend/src/modules/generate/core/services/requirements.service.ts`, `backend/src/modules/generate/core/services/generate.service.ts`, `backend/src/modules/generate/core/services/coverage.service.ts`
- OpenAI and structured-output boundary: `backend/src/modules/generate/core/services/openai.service.ts`, `backend/src/modules/generate/core/services/structured-output.service.ts`

#### Frontend workflow
The single-page React client collects credentials, source links, generation parameters, and image uploads; invokes backend source/generation APIs; then renders coverage and generated cases with CSV export. Context providers manage client-side credentials, theme, and notifications.

- Main UI composition: `frontend/src/commons/components/MainApp.tsx`, `frontend/src/features/generate/TestCaseGenerator.tsx`
- Source/API boundary: `frontend/src/features/sources/SourceInputs.tsx`, `frontend/src/commons/services/sourcesApi.ts`
- Results and export: `frontend/src/features/results/TestCaseResult.tsx`, `frontend/src/features/results/CoveragePanel.tsx`, `frontend/src/commons/utils/exportCases.ts`
- Client state boundaries: `frontend/src/commons/context/CredentialsContext.tsx`, `frontend/src/commons/context/ApiKeyContext.tsx`

#### Runtime and infrastructure
Development runs the frontend on Vite and backend on Express; production serves through the Node/Vercel-oriented entrypoint. Primary persistence is SQLite at `data/testcase-generator.db`; Vercel uses Turso per the project documentation. External dependencies are OpenAI GPT-4o, Atlassian/Confluence, and Figma.

Main entry points: [`frontend/src/features/generate/TestCaseGenerator.tsx`](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/generate/TestCaseGenerator.tsx) (Generation workflow), [`backend/src/modules/index.ts`](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/index.ts) (Feature routes), [`backend/src/modules/sources/core/controllers/sources.controller.ts`](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/sources/core/controllers/sources.controller.ts) (Source acquisition), [`backend/src/modules/generate/generate.routes.ts`](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/generate.routes.ts) (Generation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Client"]
  node_client_bootstrap["Client shell<br/>React/Vite entry<br/>[main.tsx]"]
  node_client_workflow["Generation workflow<br/>React feature UI"]
  node_source_inputs["Source inputs<br/>React source UI<br/>[SourceInputs.tsx]"]
  node_client_api["Source API client<br/>HTTP client<br/>[sourcesApi.ts]"]
  node_client_state["Credential state<br/>React contexts"]
  node_results_export["Results &amp; CSV export<br/>React results UI<br/>[TestCaseResult.tsx]"]
end

subgraph group_backend["Express API"]
  node_api_entry["API process<br/>Express entry<br/>[main.ts]"]
  node_api_app["HTTP composition<br/>Express app<br/>[app.ts]"]
  node_routes["Feature routes<br/>Route aggregator<br/>[index.ts]"]
  node_session_vault["Session vault<br/>Session service<br/>[session.service.ts]"]
  node_sources["Source acquisition<br/>Sources controller"]
  node_generation_api["Generation API<br/>Route and DTO boundary<br/>[generate.routes.ts]"]
  node_generation_graph["Generation graph<br/>Orchestrator"]
  node_model_output["GPT structured output<br/>OpenAI service<br/>[openai.service.ts]"]
end

subgraph group_data["Persistence &amp; External Services"]
  node_source_cache[("Source cache<br/>SQLite cache<br/>[source-cache.ts]")]
  node_database[("SQLite / Turso<br/>Primary persistence<br/>[client.ts]")]
  node_upstream_sources{{"Confluence &amp; Figma<br/>External source APIs"}}
  node_openai{{"OpenAI GPT-4o<br/>External model API"}}
  node_vercel_adapter["Vercel adapter<br/>Production entrypoint<br/>[index.js]"]
end

node_client_bootstrap -->|"renders"| node_client_workflow
node_client_workflow -->|"collects"| node_source_inputs
node_client_workflow -->|"uses"| node_client_state
node_source_inputs -->|"submits sources"| node_client_api
node_client_workflow -->|"requests generation"| node_generation_api
node_client_api -->|"calls"| node_sources
node_generation_api -->|"returns cases and coverage"| node_results_export
node_api_entry -->|"starts"| node_api_app
node_vercel_adapter -->|"serves production API"| node_api_app
node_api_app -->|"mounts"| node_routes
node_routes -->|"session endpoints"| node_session_vault
node_routes -->|"source endpoints"| node_sources
node_routes -->|"generation endpoints"| node_generation_api
node_session_vault -->|"encrypted sessions"| node_database
node_sources -->|"reads and writes"| node_source_cache
node_sources -->|"fetches with server credentials"| node_upstream_sources
node_generation_api -->|"validates request and starts"| node_generation_graph
node_generation_graph -->|"generates and evaluates"| node_model_output
node_model_output -->|"invokes"| node_openai
node_generation_graph -.->|"uses session credentials"| node_database

click node_client_bootstrap "https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/main.tsx"
click node_client_workflow "https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/generate/TestCaseGenerator.tsx"
click node_source_inputs "https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/sources/SourceInputs.tsx"
click node_client_api "https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/commons/services/sourcesApi.ts"
click node_client_state "https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/commons/context/CredentialsContext.tsx"
click node_results_export "https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/results/TestCaseResult.tsx"
click node_api_entry "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/main.ts"
click node_api_app "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/app.ts"
click node_routes "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/index.ts"
click node_session_vault "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/session/core/services/session.service.ts"
click node_sources "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/sources/core/controllers/sources.controller.ts"
click node_source_cache "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/db/source-cache.ts"
click node_generation_api "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/generate.routes.ts"
click node_generation_graph "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/core/graph/orchestrator.graph.ts"
click node_model_output "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/core/services/openai.service.ts"
click node_database "https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/db/client.ts"
click node_vercel_adapter "https://github.com/eswarr11/image-testcase-generator/blob/main/api/index.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_client_bootstrap,node_client_workflow,node_source_inputs,node_client_api,node_client_state,node_results_export toneBlue
class node_api_entry,node_api_app,node_routes,node_session_vault,node_sources,node_generation_api,node_generation_graph,node_model_output toneAmber
class node_source_cache,node_database,node_upstream_sources,node_openai,node_vercel_adapter toneMint
```

## Components

### React Client

- [Client shell](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/main.tsx): React/Vite entry · `frontend/src/main.tsx`
- [Generation workflow](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/generate/TestCaseGenerator.tsx): React feature UI · Collects sources, prompts, credentials, and uploads. · `frontend/src/features/generate/TestCaseGenerator.tsx`
- [Source inputs](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/sources/SourceInputs.tsx): React source UI · `frontend/src/features/sources/SourceInputs.tsx`
- [Source API client](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/commons/services/sourcesApi.ts): HTTP client · `frontend/src/commons/services/sourcesApi.ts`
- [Credential state](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/commons/context/CredentialsContext.tsx): React contexts · Client-side state excludes persisted provider secrets. · `frontend/src/commons/context/CredentialsContext.tsx`
- [Results & CSV export](https://github.com/eswarr11/image-testcase-generator/blob/main/frontend/src/features/results/TestCaseResult.tsx): React results UI · `frontend/src/features/results/TestCaseResult.tsx`

### Express API

- [API process](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/main.ts): Express entry · `backend/src/main.ts`
- [HTTP composition](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/app.ts): Express app · Applies security, CORS, tracing, error handling, and routes. · `backend/src/app.ts`
- [Feature routes](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/index.ts): Route aggregator · Combines health, session, sources, and generation endpoints. · `backend/src/modules/index.ts`
- [Session vault](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/session/core/services/session.service.ts): Session service · Keeps encrypted provider credentials behind an httpOnly session cookie. · `backend/src/modules/session/core/services/session.service.ts`
- [Source acquisition](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/sources/core/controllers/sources.controller.ts): Sources controller · Fetches and extracts Confluence and Figma source material. · `backend/src/modules/sources/core/controllers/sources.controller.ts`
- [Generation API](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/generate.routes.ts): Route and DTO boundary · `backend/src/modules/generate/generate.routes.ts`
- [Generation graph](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/core/graph/orchestrator.graph.ts): Orchestrator · Coordinates requirements, generation, and coverage stages. · `backend/src/modules/generate/core/graph/orchestrator.graph.ts`
- [GPT structured output](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/modules/generate/core/services/openai.service.ts): OpenAI service · Invokes GPT-4o and structures generated test cases. · `backend/src/modules/generate/core/services/openai.service.ts`

### Persistence & External Services

- [Source cache](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/db/source-cache.ts): SQLite cache · Caches upstream source responses. · `backend/src/db/source-cache.ts`
- [SQLite / Turso](https://github.com/eswarr11/image-testcase-generator/blob/main/backend/src/db/client.ts): Primary persistence · SQLite locally; Turso in Vercel deployments. · `backend/src/db/client.ts`
- **Confluence & Figma**: External source APIs
- **OpenAI GPT-4o**: External model API
- [Vercel adapter](https://github.com/eswarr11/image-testcase-generator/blob/main/api/index.js): Production entrypoint · `api/index.js`

## Connections

- Client shell → Generation workflow: renders
- Generation workflow → Source inputs: collects
- Generation workflow → Credential state: uses
- Source inputs → Source API client: submits sources
- Generation workflow → Generation API: requests generation
- Source API client → Source acquisition: calls
- Generation API → Results & CSV export: returns cases and coverage
- API process → HTTP composition: starts
- Vercel adapter → HTTP composition: serves production API
- HTTP composition → Feature routes: mounts
- Feature routes → Session vault: session endpoints
- Feature routes → Source acquisition: source endpoints
- Feature routes → Generation API: generation endpoints
- Session vault → SQLite / Turso: encrypted sessions
- Source acquisition → Source cache: reads and writes
- Source acquisition → Confluence & Figma: fetches with server credentials
- Generation API → Generation graph: validates request and starts
- Generation graph → GPT structured output: generates and evaluates
- GPT structured output → OpenAI GPT-4o: invokes
- Generation graph → SQLite / Turso: uses session credentials