# shirsh3/sarvashikshaai architecture

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

- Interactive diagram: https://gitdiagram.com/shirsh3/sarvashikshaai
- Repository: https://github.com/shirsh3/sarvashikshaai

## Overview

Sarvasiksha AI is a Spring Boot voice-assistant API. REST clients submit questions through the JSON endpoint, while Alexa sends skill requests to a separate endpoint; both paths call the OpenAI-backed teacher service and return answers in their respective response formats. The API also exposes a health check, and Alexa handles launch, help, stop, and session-end requests. The graph follows the sampled controllers and service; configuration details beyond the properties class are not expanded.

Main entry points: [`src/main/java/ai/sarvasiksha/service/OpenAiTeacherService.java`](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/service/OpenAiTeacherService.java) (Teacher service), [`src/main/java/ai/sarvasiksha/web/AskController.java`](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/AskController.java) (Ask API), [`src/main/java/ai/sarvasiksha/web/AlexaController.java`](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/AlexaController.java) (Alexa endpoint), [`src/main/java/ai/sarvasiksha/config/OpenAiProperties.java`](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/config/OpenAiProperties.java) (OpenAI settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client interfaces"]
  node_ask_controller["Ask API<br/>[AskController.java]"]
  node_ask_request["Ask request<br/>[AskRequest.java]"]
  node_ask_response["Ask response<br/>[AskResponse.java]"]
  node_alexa_controller["Alexa endpoint"]
  node_exception_handler["API errors"]
end

subgraph group_assistant["Answer service"]
  node_teacher_service["Teacher service"]
end

subgraph group_configuration["Configuration"]
  node_openai_properties["OpenAI settings"]
  node_application["Spring Boot app"]
end

node_rest_clients(("REST clients"))
node_alexa_platform(("Alexa platform"))
node_openai["OpenAI API"]

node_rest_clients -->|"HTTP requests"| node_ask_controller
node_ask_controller -->|"binds JSON"| node_ask_request
node_ask_controller -->|"asks question"| node_teacher_service
node_teacher_service -->|"returns answer"| node_ask_controller
node_ask_controller -->|"builds response"| node_ask_response
node_ask_controller -->|"checks key"| node_openai_properties
node_alexa_platform -->|"skill requests"| node_alexa_controller
node_alexa_controller -->|"asks question"| node_teacher_service
node_teacher_service -->|"returns answer"| node_alexa_controller
node_alexa_controller -->|"returns speech"| node_alexa_platform
node_teacher_service -->|"reads settings"| node_openai_properties
node_teacher_service -->|"sends completion request"| node_openai
node_openai -->|"returns completion"| node_teacher_service

click node_ask_controller "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/AskController.java"
click node_ask_request "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/dto/AskRequest.java"
click node_ask_response "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/dto/AskResponse.java"
click node_alexa_controller "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/AlexaController.java"
click node_exception_handler "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/ApiExceptionHandler.java"
click node_teacher_service "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/service/OpenAiTeacherService.java"
click node_openai_properties "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/config/OpenAiProperties.java"
click node_application "https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/SarvasikshaAiApplication.java"

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_ask_controller,node_ask_request,node_ask_response,node_alexa_controller,node_exception_handler,node_rest_clients toneBlue
class node_teacher_service toneAmber
class node_openai_properties,node_application,node_openai toneMint
class node_alexa_platform toneIndigo
```

## Components

### Client interfaces

- [Ask API](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/AskController.java): `src/main/java/ai/sarvasiksha/web/AskController.java`
- [Ask request](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/dto/AskRequest.java): `src/main/java/ai/sarvasiksha/dto/AskRequest.java`
- [Ask response](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/dto/AskResponse.java): `src/main/java/ai/sarvasiksha/dto/AskResponse.java`
- [Alexa endpoint](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/AlexaController.java): `src/main/java/ai/sarvasiksha/web/AlexaController.java`
- [API errors](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/web/ApiExceptionHandler.java): `src/main/java/ai/sarvasiksha/web/ApiExceptionHandler.java`

### Answer service

- [Teacher service](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/service/OpenAiTeacherService.java): `src/main/java/ai/sarvasiksha/service/OpenAiTeacherService.java`

### Configuration

- [OpenAI settings](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/config/OpenAiProperties.java): `src/main/java/ai/sarvasiksha/config/OpenAiProperties.java`
- [Spring Boot app](https://github.com/shirsh3/sarvashikshaai/blob/main/src/main/java/ai/sarvasiksha/SarvasikshaAiApplication.java): `src/main/java/ai/sarvasiksha/SarvasikshaAiApplication.java`

### Other components

- **REST clients**
- **Alexa platform**
- **OpenAI API**

## Connections

- REST clients → Ask API: HTTP requests
- Ask API → Ask request: binds JSON
- Ask API → Teacher service: asks question
- Teacher service → Ask API: returns answer
- Ask API → Ask response: builds response
- Ask API → OpenAI settings: checks key
- Alexa platform → Alexa endpoint: skill requests
- Alexa endpoint → Teacher service: asks question
- Teacher service → Alexa endpoint: returns answer
- Alexa endpoint → Alexa platform: returns speech
- Teacher service → OpenAI settings: reads settings
- Teacher service → OpenAI API: sends completion request
- OpenAI API → Teacher service: returns completion