# agilepemdigi-2026/story2gherkin architecture

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

- Interactive diagram: https://gitdiagram.com/agilepemdigi-2026/story2gherkin
- Repository: https://github.com/agilepemdigi-2026/story2gherkin

## Overview

Story2Gherkin turns a user story and GUI context into draft Given–When–Then scenarios for analyst review, correction, validation, and download. The React frontend supports authentication and role-specific workspaces; the Go API owns business processes and persistence, while the Python service provides model generation and deterministic Gherkin validation. The README describes Go–Python integration as intended but notes that their generation contracts differ, so that connection is shown as unverified. Several backend and frontend implementation files were not sampled; their internal calls are not inferred.

Main entry points: [`backend/cmd/main.go`](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/cmd/main.go) (Go REST API entry), [`frontend/src/App.tsx`](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/App.tsx) (Role-based app routes), [`frontend/src/pages/ReviewScenarioPage.tsx`](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/pages/ReviewScenarioPage.tsx) (Scenario review workspace), [`backend/modules/scenario/routes.go`](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/routes.go) (Scenario API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React user interface"]
  node_web["Role-based app routes<br/>[App.tsx]"]
  node_auth_ui["Sign-in and session<br/>[authSession.ts]"]
  node_generate_ui["Scenario generation page"]
  node_review_ui["Scenario review workspace"]
  node_review_widgets["Editor and validation panels<br/>[GherkinEditor.tsx]"]
  node_auth_api_ui["Authentication API client<br/>[authApi.ts]"]
  node_scenario_api_ui["Scenario API client<br/>[scenarioApi.ts]"]
  node_review_api_ui["Review API client<br/>[reviewApi.ts]"]
end

subgraph group_backend["Go API and persistence"]
  node_go_api["Go REST API entry<br/>[main.go]"]
  node_auth["Authentication and tokens<br/>[auth_handler.go]"]
  node_users["User accounts<br/>[user_repository.go]"]
  node_scenario_routes["Scenario API routes<br/>[routes.go]"]
  node_generation["Scenario generation service"]
  node_llm_bridge["AI service client<br/>[llm_client.go]"]
  node_review_handler["Review handlers<br/>[review_handler.go]"]
  node_review_service["Review and correction logic<br/>[review_service.go]"]
  node_review_store["Review repository"]
end

subgraph group_ai["Python AI service"]
  node_ai_api["Internal FastAPI routes<br/>[main.py]"]
  node_ai_generate_route["Generate endpoint<br/>[generate.py]"]
  node_ai_generator["Gherkin generation and parsing<br/>[generator.py]"]
  node_prompts["Prompt construction<br/>[prompts.py]"]
  node_model_clients["Ollama / OpenRouter clients<br/>[ollama.py]"]
  node_ai_review_route["Validation endpoint<br/>[review.py]"]
  node_gherkin_validation["Gherkin validation and coverage<br/>[validation.py]"]
end

subgraph group_data["Scenario data"]
  node_database[("PostgreSQL")]
end

node_analyst(("System analyst / QA"))
node_model{{"LLM provider"}}

node_analyst -->|"uses"| node_web
node_web -->|"routes to"| node_auth_ui
node_web -->|"routes to"| node_generate_ui
node_web -->|"routes to"| node_review_ui
node_auth_ui -.->|"calls"| node_auth_api_ui
node_generate_ui -.->|"calls"| node_scenario_api_ui
node_review_ui -->|"calls"| node_review_api_ui
node_review_ui -->|"renders"| node_review_widgets
node_auth_api_ui -.->|"requests"| node_go_api
node_scenario_api_ui -.->|"requests"| node_go_api
node_review_api_ui -.->|"requests"| node_go_api
node_go_api -.->|"dispatches"| node_auth
node_go_api -.->|"dispatches"| node_scenario_routes
node_auth -.->|"uses"| node_users
node_scenario_routes -.->|"dispatches"| node_generation
node_scenario_routes -.->|"dispatches"| node_review_handler
node_generation -.->|"requests generation"| node_llm_bridge
node_llm_bridge -.->|"calls"| node_ai_api
node_review_handler -.->|"delegates to"| node_review_service
node_review_service -.->|"uses"| node_review_store
node_review_store -.->|"reads and writes"| node_database
node_ai_api -->|"registers"| node_ai_generate_route
node_ai_api -->|"registers"| node_ai_review_route
node_ai_generate_route -->|"invokes"| node_ai_generator
node_ai_generator -->|"uses"| node_prompts
node_ai_generator -.->|"calls"| node_model_clients
node_model_clients -->|"sends prompts"| node_model
node_ai_review_route -->|"calls"| node_gherkin_validation

click node_web "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/authSession.ts"
click node_generate_ui "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/pages/GenerateScenarioPage.tsx"
click node_review_ui "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/pages/ReviewScenarioPage.tsx"
click node_review_widgets "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/components/review/GherkinEditor.tsx"
click node_auth_api_ui "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/authApi.ts"
click node_scenario_api_ui "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/scenarioApi.ts"
click node_review_api_ui "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/reviewApi.ts"
click node_go_api "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/cmd/main.go"
click node_auth "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/auth/handler/auth_handler.go"
click node_users "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/user/repository/user_repository.go"
click node_scenario_routes "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/routes.go"
click node_generation "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/service/scenario_service.go"
click node_llm_bridge "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/service/llm_client.go"
click node_review_handler "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/handler/review_handler.go"
click node_review_service "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/service/review_service.go"
click node_review_store "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/repository/review_repository.go"
click node_ai_api "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/main.py"
click node_ai_generate_route "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/api/routes/generate.py"
click node_ai_generator "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/services/generator.py"
click node_prompts "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/services/prompts.py"
click node_model_clients "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/clients/ollama.py"
click node_ai_review_route "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/api/routes/review.py"
click node_gherkin_validation "https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/services/validation.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_auth_ui,node_generate_ui,node_review_ui,node_review_widgets,node_auth_api_ui,node_scenario_api_ui,node_review_api_ui toneBlue
class node_go_api,node_auth,node_users,node_scenario_routes,node_generation,node_llm_bridge,node_review_handler,node_review_service,node_review_store toneAmber
class node_ai_api,node_ai_generate_route,node_ai_generator,node_prompts,node_model_clients,node_ai_review_route,node_gherkin_validation toneMint
class node_database toneRose
class node_analyst,node_model toneIndigo
```

## Components

### React user interface

- [Role-based app routes](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in and session](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/authSession.ts): `frontend/src/services/authSession.ts`
- [Scenario generation page](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/pages/GenerateScenarioPage.tsx): `frontend/src/pages/GenerateScenarioPage.tsx`
- [Scenario review workspace](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/pages/ReviewScenarioPage.tsx): `frontend/src/pages/ReviewScenarioPage.tsx`
- [Editor and validation panels](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/components/review/GherkinEditor.tsx): `frontend/src/components/review/GherkinEditor.tsx`
- [Authentication API client](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/authApi.ts): `frontend/src/services/authApi.ts`
- [Scenario API client](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/scenarioApi.ts): `frontend/src/services/scenarioApi.ts`
- [Review API client](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/frontend/src/services/reviewApi.ts): `frontend/src/services/reviewApi.ts`

### Go API and persistence

- [Go REST API entry](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/cmd/main.go): `backend/cmd/main.go`
- [Authentication and tokens](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/auth/handler/auth_handler.go): `backend/modules/auth/handler/auth_handler.go`
- [User accounts](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/user/repository/user_repository.go): `backend/modules/user/repository/user_repository.go`
- [Scenario API routes](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/routes.go): `backend/modules/scenario/routes.go`
- [Scenario generation service](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/service/scenario_service.go): `backend/modules/scenario/service/scenario_service.go`
- [AI service client](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/service/llm_client.go): `backend/modules/scenario/service/llm_client.go`
- [Review handlers](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/handler/review_handler.go): `backend/modules/scenario/handler/review_handler.go`
- [Review and correction logic](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/service/review_service.go): `backend/modules/scenario/service/review_service.go`
- [Review repository](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/backend/modules/scenario/repository/review_repository.go): `backend/modules/scenario/repository/review_repository.go`

### Python AI service

- [Internal FastAPI routes](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Generate endpoint](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/api/routes/generate.py): `ai-service/app/api/routes/generate.py`
- [Gherkin generation and parsing](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/services/generator.py): `ai-service/app/services/generator.py`
- [Prompt construction](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/services/prompts.py): `ai-service/app/services/prompts.py`
- [Ollama / OpenRouter clients](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/clients/ollama.py): `ai-service/app/clients/ollama.py`
- [Validation endpoint](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/api/routes/review.py): `ai-service/app/api/routes/review.py`
- [Gherkin validation and coverage](https://github.com/agilepemdigi-2026/story2gherkin/blob/main/ai-service/app/services/validation.py): `ai-service/app/services/validation.py`

### Scenario data

- **PostgreSQL**

### Other components

- **System analyst / QA**
- **LLM provider**

## Connections

- System analyst / QA → Role-based app routes: uses (evidence: `frontend/src/App.tsx`)
- Role-based app routes → Sign-in and session: routes to (evidence: `frontend/src/App.tsx`)
- Role-based app routes → Scenario generation page: routes to (evidence: `frontend/src/App.tsx`)
- Role-based app routes → Scenario review workspace: routes to (evidence: `frontend/src/App.tsx`)
- Sign-in and session → Authentication API client: calls (evidence: `frontend/src/services/authSession.ts`)
- Scenario generation page → Scenario API client: calls
- Scenario review workspace → Review API client: calls (evidence: `frontend/src/pages/ReviewScenarioPage.tsx`)
- Scenario review workspace → Editor and validation panels: renders (evidence: `frontend/src/pages/ReviewScenarioPage.tsx`)
- Authentication API client → Go REST API entry: requests
- Scenario API client → Go REST API entry: requests
- Review API client → Go REST API entry: requests
- Go REST API entry → Authentication and tokens: dispatches
- Go REST API entry → Scenario API routes: dispatches
- Authentication and tokens → User accounts: uses
- Scenario API routes → Scenario generation service: dispatches
- Scenario API routes → Review handlers: dispatches
- Scenario generation service → AI service client: requests generation
- AI service client → Internal FastAPI routes: calls (evidence: `README.md`)
- Review handlers → Review and correction logic: delegates to
- Review and correction logic → Review repository: uses
- Review repository → PostgreSQL: reads and writes
- Internal FastAPI routes → Generate endpoint: registers (evidence: `ai-service/app/main.py`)
- Internal FastAPI routes → Validation endpoint: registers (evidence: `ai-service/app/main.py`)
- Generate endpoint → Gherkin generation and parsing: invokes (evidence: `ai-service/app/api/routes/generate.py`)
- Gherkin generation and parsing → Prompt construction: uses (evidence: `ai-service/app/services/generator.py`)
- Gherkin generation and parsing → Ollama / OpenRouter clients: calls
- Ollama / OpenRouter clients → LLM provider: sends prompts
- Validation endpoint → Gherkin validation and coverage: calls (evidence: `ai-service/app/api/routes/review.py`)