# zoomish/interview-assistant architecture

> Architecture diagram of the GitHub repository zoomish/interview-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zoomish/interview-assistant
- Repository: https://github.com/zoomish/interview-assistant

## Overview

##### Project type and purpose
- This is a backend microservice: a Telegram bot for interview preparation built with Nest.js.
- It uses the node-telegram-bot-api to interface with Telegram, Postgres via TypeORM for persistence, and the Gemini AI API for dynamic question generation.

##### File structure
- Top‑level Nest.js app: src/app.module.ts, src/main.ts
- Bot module: src/bot
- bot.module.ts & bot.service.ts – core Telegram integration
- services/handling – command‑level handlers (greeting, help, AI generation, speech‑to‑text, etc.)
- services/callback – inline‑keyboard callbacks (announcement, history, interview, review, user profile edits)
- Domain modules:
- src/user – User entity, DTOs, UserService
- src/history – History entity, DTOs, HistoryService
- src/review – Review entity, DTOs, ReviewService
- Configuration: example.env, nest-cli.json, tsconfig.json
- Dependencies: node-telegram-bot-api, @nestjs/*, TypeORM, pg, Gemini API client

##### README for additional insights
- Features: profession- and skill‑based Q&A, AI‑generated dynamic content, persistent user profiles & histories
- Deployment hints: long‑polling vs webhook, environment variables for Telegram token, Gemini API key, Postgres credentials

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "External Systems"
    Telegram["Telegram API"]:::external
    Gemini["Gemini AI API"]:::external
    Postgres[(Postgres DB)]:::db
  end

  subgraph "Infrastructure"
    Main["Application Entry Point\n(main.ts)"]:::nest
    AppModule["NestJS Core Module\n(app.module.ts)"]:::nest
    BotModule["Bot Module\n(bot.module.ts)"]:::nest
    BotService["Telegram Gateway\n(BotService)"]:::nest
  end

  subgraph "Application Logic"
    HandleService["Generic Handle Service"]:::handler
    HandlersDir["Command Handlers"]:::handler
    Greeting["Greeting Handler"]:::handler
    Help["Help Handler"]:::handler
    AIGroup["AI Command Handlers"]:::handler
    AIStart["AI Start Service"]:::handler
    AIGen["AI Content Generation"]:::handler
    Announcement["Announcement Handler"]:::handler
    InterviewHandler["Interview Handler"]:::handler
    ReviewHandler["Review Handler"]:::handler
    SpeechToText["Speech-to-Text Handler"]:::handler
    UserGroup["User Handlers"]:::handler
    MeService["Me Service"]:::handler

    CallbackDir["Callback Handlers"]:::callback
    GenericCallback["Generic Callback"]:::callback
    AnnouncementCB["Announcement Callback"]:::callback
    HistoryCB["History Callback"]:::callback
    InterviewCB["Interview Callback"]:::callback
    ReviewEditCB["Review Edit Callback"]:::callback
    UserCBGroup["User Profile Callbacks"]:::callback
    EditLevel["Edit Level"]:::callback
    EditProfession["Edit Profession"]:::callback
    EditSkills["Edit Skills"]:::callback
  end

  subgraph "Domain & Persistence"
    UserModule["User Module"]:::nest
    UserService["User Service"]:::domain
    UserEntity["User Entity"]:::domain
    UserDTO["User DTOs"]:::domain

    HistoryModule["History Module"]:::nest
    HistoryService["History Service"]:::domain
    HistoryEntity["History Entity"]:::domain
    HistoryDTO["History DTOs"]:::domain

    ReviewModule["Review Module"]:::nest
    ReviewService["Review Service"]:::domain
    ReviewEntity["Review Entity"]:::domain
    ReviewDTO["Review DTOs"]:::domain
  end

  Telegram -->|updates| BotService
  BotService -->|dispatch| HandleService
  BotService -->|dispatch| GenericCallback
  HandleService -->|routes to| HandlersDir
  HandlersDir --> Greeting
  HandlersDir --> Help
  HandlersDir --> AIGroup
  HandlersDir --> Announcement
  HandlersDir --> InterviewHandler
  HandlersDir --> ReviewHandler
  HandlersDir --> SpeechToText
  HandlersDir --> UserGroup
  AIGroup --> AIStart
  AIStart --> AIGen
  AIStart -->|calls| Gemini
  AIGen -->|calls| Gemini
  GenericCallback -->|routes to| CallbackDir
  CallbackDir --> AnnouncementCB
  CallbackDir --> HistoryCB
  CallbackDir --> InterviewCB
  CallbackDir --> ReviewEditCB
  CallbackDir --> UserCBGroup
  UserCBGroup --> EditLevel
  UserCBGroup --> EditProfession
  UserCBGroup --> EditSkills

  Greeting -->|uses| UserService
  Help -->|uses| UserService
  Announcement -->|uses| HistoryService
  InterviewHandler -->|uses| HistoryService
  ReviewHandler -->|uses| ReviewService
  SpeechToText -->|uses| UserService
  MeService -->|uses| UserService

  UserService -->|CRUD| Postgres
  HistoryService -->|CRUD| Postgres
  ReviewService -->|CRUD| Postgres

  BotService -->|responses| Telegram

  Main --> AppModule
  AppModule --> BotModule
  AppModule --> UserModule
  AppModule --> HistoryModule
  AppModule --> ReviewModule
  BotModule --> BotService

  classDef external fill:#add8e6,stroke:#333,stroke-width:1px
  classDef nest fill:#90ee90,stroke:#333,stroke-width:1px,rx:5,ry:5
  classDef handler fill:#ffcc99,stroke:#333,stroke-width:1px,rx:5,ry:5
  classDef callback fill:#ffdead,stroke:#333,stroke-width:1px,rx:5,ry:5
  classDef domain fill:#f0e68c,stroke:#333,stroke-width:1px
  classDef db fill:#ffa500,stroke:#333,stroke-width:1px

  click Main "https://github.com/zoomish/interview-assistant/blob/main/src/main.ts"
  click AppModule "https://github.com/zoomish/interview-assistant/blob/main/src/app.module.ts"
  click BotModule "https://github.com/zoomish/interview-assistant/blob/main/src/bot/bot.module.ts"
  click BotService "https://github.com/zoomish/interview-assistant/blob/main/src/bot/bot.service.ts"
  click HandleService "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handle.service.ts"
  click HandlersDir "https://github.com/zoomish/interview-assistant/tree/main/src/bot/services/handling"
  click Greeting "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/greeting.service.ts"
  click Help "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/help.service.ts"
  click AIGroup "https://github.com/zoomish/interview-assistant/tree/main/src/bot/services/handling/ai"
  click AIStart "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/ai/aiStart.service.ts"
  click AIGen "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/ai/generateContent.service.ts"
  click Announcement "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/announcement/announcement.service.ts"
  click InterviewHandler "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/interview.service.ts"
  click ReviewHandler "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/review.service.ts"
  click SpeechToText "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/speechToText/speech-to-text.service.ts"
  click UserGroup "https://github.com/zoomish/interview-assistant/tree/main/src/bot/services/handling/user"
  click MeService "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/handling/user/me.service.ts"
  click CallbackDir "https://github.com/zoomish/interview-assistant/tree/main/src/bot/services/callback"
  click GenericCallback "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/callback.service.ts"
  click AnnouncementCB "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/announcement/announcement.service.ts"
  click HistoryCB "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/history/history.service.ts"
  click InterviewCB "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/interview/interview.service.ts"
  click ReviewEditCB "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/review/editReview.service.ts"
  click UserCBGroup "https://github.com/zoomish/interview-assistant/tree/main/src/bot/services/callback/user"
  click EditLevel "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/user/level/editLevel.service.ts"
  click EditProfession "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/user/profession/editProfession.service.ts"
  click EditSkills "https://github.com/zoomish/interview-assistant/blob/main/src/bot/services/callback/user/skills/editSkills.service.ts"
  click UserModule "https://github.com/zoomish/interview-assistant/blob/main/src/user/user.module.ts"
  click UserService "https://github.com/zoomish/interview-assistant/blob/main/src/user/user.service.ts"
  click UserEntity "https://github.com/zoomish/interview-assistant/blob/main/src/user/entities/user.entity.ts"
  click UserDTO "https://github.com/zoomish/interview-assistant/blob/main/src/user/dto/create-user.dto.ts"
  click HistoryModule "https://github.com/zoomish/interview-assistant/blob/main/src/history/history.module.ts"
  click HistoryService "https://github.com/zoomish/interview-assistant/blob/main/src/history/history.service.ts"
  click HistoryEntity "https://github.com/zoomish/interview-assistant/blob/main/src/history/entities/history.entity.ts"
  click HistoryDTO "https://github.com/zoomish/interview-assistant/blob/main/src/history/dto/create-history.dto.ts"
  click ReviewModule "https://github.com/zoomish/interview-assistant/blob/main/src/review/review.module.ts"
  click ReviewService "https://github.com/zoomish/interview-assistant/blob/main/src/review/review.service.ts"
  click ReviewEntity "https://github.com/zoomish/interview-assistant/blob/main/src/review/entities/review.entity.ts"
  click ReviewDTO "https://github.com/zoomish/interview-assistant/blob/main/src/review/dto/create-review.dto.ts"
```
