# marsels-str/ai-pieturas architecture

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

- Interactive diagram: https://gitdiagram.com/marsels-str/ai-pieturas
- Repository: https://github.com/marsels-str/ai-pieturas

## Overview

This Laravel application manages Latvian stop information and its multilingual text and audio. Administrators and users work through web screens to maintain stops, languages, translations, history, and accounts; synchronization queues translation and MP3-generation work. A separate access workflow collects API requests, lets administrators approve or block access, and serves stop data to key-holders. The README documents OpenAI translation and ElevenLabs speech, though sampled source does not show the jobs’ complete service wiring or all route connections.

Main entry points: [`app/Http/Controllers/ApiAccessController.php`](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ApiAccessController.php) (API access workflow), [`app/Http/Controllers/ValodasController.php`](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ValodasController.php) (Translation management), [`app/Services/OpenAITranslator.php`](https://github.com/marsels-str/ai-pieturas/blob/main/app/Services/OpenAITranslator.php) (OpenAI translator), [`app/Http/Controllers/Mp3Controller.php`](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/Mp3Controller.php) (MP3 management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web management"]
  node_pieturas_ctrl["Stop management"]
  node_users_ctrl["User management<br/>[UserController.php]"]
  node_auth_ctrl["Authentication"]
  node_profile_ctrl["Profile"]
end

subgraph group_localization["Language workflows"]
  node_translation_ctrl["Translation management"]
  node_translation_job["Translation job"]
  node_translation_service["OpenAI translator"]
  node_lang_commands["Locale commands"]
  node_lang_translate_cmd["Locale translation command"]
end

subgraph group_audio["Audio generation"]
  node_mp3_ctrl["MP3 management<br/>[Mp3Controller.php]"]
  node_mp3_job["MP3 generation job<br/>[GenerateMp3Job.php]"]
  node_tts_service["Text-to-speech service"]
end

subgraph group_api["API access"]
  node_api_access_ctrl["API access workflow"]
  node_api_middleware["API key check<br/>[CheckApiKey.php]"]
end

subgraph group_data["Application data"]
  node_pieturas_model[("Stops<br/>[Pieturas.php]")]
  node_language_models[("Language and text<br/>[Valodas.php]")]
  node_originals_model[("Original texts<br/>[Originals.php]")]
  node_translations_model[("Translations<br/>[Tulkojums.php]")]
  node_history_model[("Stop history<br/>[Vesture.php]")]
  node_api_request_model[("API requests<br/>[ApiRequest.php]")]
  node_api_key_model[("API keys<br/>[ApiKey.php]")]
  node_pending_key_model[("Pending keys<br/>[PendingKey.php]")]
  node_user_model[("Users<br/>[User.php]")]
end

node_admin(("Administrator"))
node_user(("Web user"))
node_api_client(("API client"))
node_elevenlabs{{"ElevenLabs"}}
node_openai{{"OpenAI<br/>external service"}}

node_user -->|"signs in"| node_auth_ctrl
node_user -->|"updates profile"| node_profile_ctrl
node_admin -->|"manages stops"| node_pieturas_ctrl
node_admin -->|"manages users"| node_users_ctrl
node_admin -->|"manages languages"| node_translation_ctrl
node_admin -->|"starts sync"| node_mp3_ctrl
node_auth_ctrl -->|"authenticates"| node_user_model
node_users_ctrl -->|"manages"| node_user_model
node_pieturas_ctrl -->|"reads and writes"| node_pieturas_model
node_translation_ctrl -->|"reads and writes"| node_language_models
node_translation_ctrl -->|"reads"| node_originals_model
node_translation_ctrl -->|"dispatches batch"| node_translation_job
node_lang_commands -.->|"prepares locales"| node_lang_translate_cmd
node_translation_job -.->|"invokes"| node_translation_service
node_translation_service -.->|"stores translations"| node_translations_model
node_translation_service -.->|"requests translation"| node_openai
node_admin -->|"prepares locale files"| node_lang_commands
node_mp3_ctrl -->|"reads versions"| node_history_model
node_mp3_ctrl -->|"dispatches batch"| node_mp3_job
node_mp3_job -.->|"invokes"| node_tts_service
node_tts_service -->|"requests speech"| node_elevenlabs
node_api_client -->|"requests stops"| node_api_access_ctrl
node_admin -->|"reviews requests"| node_api_access_ctrl
node_api_access_ctrl -->|"reads and writes"| node_api_request_model
node_api_access_ctrl -->|"creates and deletes"| node_api_key_model
node_api_access_ctrl -->|"creates and checks"| node_pending_key_model
node_api_access_ctrl -->|"reads stops"| node_pieturas_model
node_api_middleware -.->|"checks key"| node_api_key_model

click node_pieturas_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/PieturasController.php"
click node_users_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/UserController.php"
click node_auth_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/Auth/AuthenticatedSessionController.php"
click node_profile_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ProfileController.php"
click node_translation_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ValodasController.php"
click node_translation_job "https://github.com/marsels-str/ai-pieturas/blob/main/app/Jobs/TranslateOriginalJob.php"
click node_translation_service "https://github.com/marsels-str/ai-pieturas/blob/main/app/Services/OpenAITranslator.php"
click node_lang_commands "https://github.com/marsels-str/ai-pieturas/blob/main/app/Console/Commands/PrepareLangFiles.php"
click node_lang_translate_cmd "https://github.com/marsels-str/ai-pieturas/blob/main/app/Console/Commands/TranslateLangFiles.php"
click node_mp3_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/Mp3Controller.php"
click node_mp3_job "https://github.com/marsels-str/ai-pieturas/blob/main/app/Jobs/GenerateMp3Job.php"
click node_tts_service "https://github.com/marsels-str/ai-pieturas/blob/main/app/Services/TextToSpeechService.php"
click node_api_access_ctrl "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ApiAccessController.php"
click node_api_middleware "https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Middleware/CheckApiKey.php"
click node_pieturas_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Pieturas.php"
click node_language_models "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Valodas.php"
click node_originals_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Originals.php"
click node_translations_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Tulkojums.php"
click node_history_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Vesture.php"
click node_api_request_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/ApiRequest.php"
click node_api_key_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/ApiKey.php"
click node_pending_key_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/PendingKey.php"
click node_user_model "https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/User.php"

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_pieturas_ctrl,node_users_ctrl,node_auth_ctrl,node_profile_ctrl,node_user,node_api_client toneBlue
class node_translation_ctrl,node_translation_job,node_translation_service,node_lang_commands,node_lang_translate_cmd toneAmber
class node_mp3_ctrl,node_mp3_job,node_tts_service toneMint
class node_api_access_ctrl,node_api_middleware toneRose
class node_pieturas_model,node_language_models,node_originals_model,node_translations_model,node_history_model,node_api_request_model,node_api_key_model,node_pending_key_model,node_user_model,node_admin,node_elevenlabs,node_openai toneIndigo
```

## Components

### Web management

- [Stop management](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/PieturasController.php): `app/Http/Controllers/PieturasController.php`
- [User management](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/UserController.php): `app/Http/Controllers/UserController.php`
- [Authentication](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/Auth/AuthenticatedSessionController.php): `app/Http/Controllers/Auth/AuthenticatedSessionController.php`
- [Profile](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ProfileController.php): `app/Http/Controllers/ProfileController.php`

### Language workflows

- [Translation management](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ValodasController.php): `app/Http/Controllers/ValodasController.php`
- [Translation job](https://github.com/marsels-str/ai-pieturas/blob/main/app/Jobs/TranslateOriginalJob.php): `app/Jobs/TranslateOriginalJob.php`
- [OpenAI translator](https://github.com/marsels-str/ai-pieturas/blob/main/app/Services/OpenAITranslator.php): `app/Services/OpenAITranslator.php`
- [Locale commands](https://github.com/marsels-str/ai-pieturas/blob/main/app/Console/Commands/PrepareLangFiles.php): `app/Console/Commands/PrepareLangFiles.php`
- [Locale translation command](https://github.com/marsels-str/ai-pieturas/blob/main/app/Console/Commands/TranslateLangFiles.php): `app/Console/Commands/TranslateLangFiles.php`

### Audio generation

- [MP3 management](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/Mp3Controller.php): `app/Http/Controllers/Mp3Controller.php`
- [MP3 generation job](https://github.com/marsels-str/ai-pieturas/blob/main/app/Jobs/GenerateMp3Job.php): `app/Jobs/GenerateMp3Job.php`
- [Text-to-speech service](https://github.com/marsels-str/ai-pieturas/blob/main/app/Services/TextToSpeechService.php): `app/Services/TextToSpeechService.php`

### API access

- [API access workflow](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Controllers/ApiAccessController.php): `app/Http/Controllers/ApiAccessController.php`
- [API key check](https://github.com/marsels-str/ai-pieturas/blob/main/app/Http/Middleware/CheckApiKey.php): `app/Http/Middleware/CheckApiKey.php`

### Application data

- [Stops](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Pieturas.php): `app/Models/Pieturas.php`
- [Language and text](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Valodas.php): `app/Models/Valodas.php`
- [Original texts](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Originals.php): `app/Models/Originals.php`
- [Translations](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Tulkojums.php): `app/Models/Tulkojums.php`
- [Stop history](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/Vesture.php): `app/Models/Vesture.php`
- [API requests](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/ApiRequest.php): `app/Models/ApiRequest.php`
- [API keys](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/ApiKey.php): `app/Models/ApiKey.php`
- [Pending keys](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/PendingKey.php): `app/Models/PendingKey.php`
- [Users](https://github.com/marsels-str/ai-pieturas/blob/main/app/Models/User.php): `app/Models/User.php`

### Other components

- **Administrator**
- **Web user**
- **API client**
- **ElevenLabs**
- **OpenAI**: external service

## Connections

- Web user → Authentication: signs in
- Web user → Profile: updates profile
- Administrator → Stop management: manages stops
- Administrator → User management: manages users
- Administrator → Translation management: manages languages
- Administrator → MP3 management: starts sync
- Authentication → Users: authenticates
- User management → Users: manages
- Stop management → Stops: reads and writes
- Translation management → Language and text: reads and writes
- Translation management → Original texts: reads
- Translation management → Translation job: dispatches batch
- Locale commands → Locale translation command: prepares locales
- Translation job → OpenAI translator: invokes
- OpenAI translator → Translations: stores translations
- OpenAI translator → OpenAI: requests translation
- Administrator → Locale commands: prepares locale files
- MP3 management → Stop history: reads versions
- MP3 management → MP3 generation job: dispatches batch
- MP3 generation job → Text-to-speech service: invokes
- Text-to-speech service → ElevenLabs: requests speech
- API client → API access workflow: requests stops
- Administrator → API access workflow: reviews requests
- API access workflow → API requests: reads and writes
- API access workflow → API keys: creates and deletes
- API access workflow → Pending keys: creates and checks
- API access workflow → Stops: reads stops
- API key check → API keys: checks key