# snailclimb/interview-guide architecture

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

- Interactive diagram: https://gitdiagram.com/snailclimb/interview-guide
- Repository: https://github.com/snailclimb/interview-guide

## Overview

1. **System shape**
   - This is a two-tier application: a **React + TypeScript frontend** and a **Spring Boot 4 / Java 21 backend**.
   - The backend is the real orchestration layer; it owns business logic, persistence, async processing, AI calls, file handling, and report generation.

2. **Frontend boundary**
   - The `frontend/` app is a SPA built with Vite, React Router, Tailwind, and a few UI/data libraries.
   - It is split into `pages/`, `components/`, `api/`, `types/`, and `utils/`, which suggests a thin presentation layer that talks to the backend through API modules rather than embedding business logic.
   - The frontend also consumes streaming/interactive APIs for chat and live status updates.

3. **Backend package structure**
   - `app/src/main/java/interview/guide/` is organized into:
     - `common/` for cross-cutting concerns,
     - `infrastructure/` for storage, Redis, file parsing, PDF export, and mapping,
     - `modules/` for the three business domains: **resume**, **interview**, and **knowledgebase**.
   - This is a clear layered architecture: controllers → services → repositories/infrastructure.

4. **Cross-cutting concerns**
   - `common/exception` provides a global error model and handler.
   - `common/result/Result` standardizes API responses.
   - `common/annotation/RateLimit` plus `common/aspect/RateLimitAspect` implements request throttling using Redis-backed Lua scripting (`src/main/resources/scripts/rate_limit.lua`).
   - `common/ai/StructuredOutputInvoker` is a shared AI utility for forcing LLM responses into structured DTOs.

5. **Infrastructure services**
   - `infrastructure/file` contains the document ingestion pipeline: content-type detection, validation, hashing, parsing, and text cleanup.
   - `infrastructure/export/PdfExportService` generates downloadable PDF reports.
   - `infrastructure/redis` wraps Redis usage both as a cache and as the Stream backbone for background jobs.
   - `infrastructure/mapper` contains MapStruct mappers between JPA entities and DTOs.

6. **Persistent storage boundaries**
   - **PostgreSQL** is the main relational store for resumes, interviews, knowledge base metadata, chat messages, and analysis records.
   - **pgvector** is used for semantic search/vector storage in the knowledge base.
   - **Redis** serves two roles:
     - cache/session storage for live interaction state,
     - message transport for async workflows via Redis Stream.
   - **S3-compatible object storage** (MinIO/RustFS in Docker) stores uploaded source files and generated artifacts.

7. **Resume subsystem**
   - Entry point is `ResumeController`.
   - Upload flow: file upload → parse/validate/hash/store file → persist resume metadata → enqueue analysis job.
   - Async analysis is handled by `AnalyzeStreamProducer` / `AnalyzeStreamConsumer`.
   - The module keeps separate entities for the resume itself and the analysis result, with services for upload, parsing, persistence, grading, history, and deletion.
   - The main user-visible state machine is `PENDING` → `PROCESSING` → `COMPLETED` / `FAILED`.

8. **Interview subsystem**
   - Entry point is `InterviewController`.
   - It builds a mock interview session from resume data, generates questions, accepts answers, and produces evaluation/report data.
   - `EvaluateStreamProducer` / `EvaluateStreamConsumer` offload answer evaluation and report generation to Redis Stream so the API can return quickly.
   - The module persists interview sessions and answers separately, which supports history/detail/report views.

9. **Knowledge base subsystem**
   - Entry points are `KnowledgeBaseController` and `RagChatController`.
   - Upload flow: document upload → parse/chunk/clean → persist knowledge base record → enqueue vectorization job.
   - `VectorizeStreamProducer` / `VectorizeStreamConsumer` handle embedding generation and vector-store writes asynchronously.
   - Query flow uses RAG: rewrite/query expansion, vector retrieval from pgvector, then LLM-generated responses.
   - Chat history is stored with session/message entities, and the query path supports SSE-style streaming responses for the UI.

10. **AI integration points**
   - The backend uses Spring AI plus prompt templates in `src/main/resources/prompts/`.
   - Prompt files exist for:
     - resume analysis,
     - interview question generation,
     - interview answer evaluation and summary,
     - knowledge base query rewriting and answer generation.
   - AI output is used in a structured way, not as raw text only, which is important for diagramming: LLM output feeds DTOs, not just UI text.

11. **Async processing pattern**
   - A common architectural pattern runs across resume, interview, and knowledge base:
     - user submits request,
     - backend stores file/record and immediately returns,
     - a Redis Stream producer publishes a job,
     - consumer processes the job,
     - database status is updated,
     - frontend polls or streams status until completion.
   - This is the key decoupling mechanism in the system.

12. **Deployment topology**
   - The repo includes Docker support for the full stack: backend app, frontend, PostgreSQL, Redis, and object storage.
   - `docker-compose.yml` and `docker/postgres/init.sql` indicate the project is designed to run locally with its infrastructure dependencies bundled.
   - The backend exposes API traffic on `8080`, while the frontend is served separately in the containerized setup.

13. **What to show in an architecture diagram**
   - Draw three main application domains inside the backend: **Resume**, **Interview**, **Knowledge Base**.
   - Show shared platform services beneath them: **PostgreSQL/pgvector**, **Redis Streams/cache**, and **S3 storage**.
   - Show **LLM/Spring AI** as an external dependency reached by all three domains through prompt-driven services.
   - Show the frontend as a separate client consuming REST plus streaming APIs.
   - Make the async job path explicit, because it is one of the central design choices of the repo.

Main entry points: [`app/src/main/java/interview/guide/App.java`](https://github.com/snailclimb/interview-guide/blob/master/app/src/main/java/interview/guide/App.java) (Spring App), [`app/src/main/java/interview/guide/modules/knowledgebase`](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/knowledgebase) (Knowledge Base), [`app/src/main/java/interview/guide/modules/resume`](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/resume) (Resume Domain), [`app/src/main/java/interview/guide/modules/interview`](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/interview) (Interview Domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["React SPA<br/>client app<br/>[App.tsx]"]
  node_frontend_api["API Client<br/>http/stream client"]
  node_frontend_pages["Pages<br/>views"]
  node_frontend_components["UI Components"]
end

subgraph group_backend["Backend"]
  node_backend_app["Spring App<br/>bootstrap<br/>[App.java]"]
  node_backend_common["Common Layer<br/>cross-cutting"]
  node_backend_infra["Infrastructure<br/>platform services"]
  node_resume_domain["Resume Domain<br/>business module"]
  node_resume_async["Resume Jobs<br/>async workflow"]
  node_interview_domain["Interview Domain<br/>business module"]
  node_interview_async["Interview Jobs<br/>async workflow"]
  node_kb_domain["Knowledge Base<br/>business module"]
  node_kb_async["Vector Jobs<br/>async workflow"]
end

subgraph group_shared["Shared Platform"]
end

subgraph group_external["External Systems"]
  node_postgres[("PostgreSQL<br/>relational store")]
  node_pgvector[("pgvector<br/>vector store")]
  node_redis[("Redis<br/>cache/streams")]
  node_object_storage[("Object Storage<br/>file store")]
  node_llm(("LLM Service<br/>ai dependency"))
end

node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_pages -->|"composes"| node_frontend_components
node_frontend_api -->|"REST/SSE"| node_backend_app
node_backend_app -->|"shares"| node_backend_common
node_backend_app -->|"uses"| node_backend_infra
node_backend_app -->|"hosts"| node_resume_domain
node_backend_app -->|"hosts"| node_interview_domain
node_backend_app -->|"hosts"| node_kb_domain
node_resume_domain -->|"offloads"| node_resume_async
node_interview_domain -->|"offloads"| node_interview_async
node_kb_domain -->|"offloads"| node_kb_async
node_resume_domain -->|"persists"| node_postgres
node_interview_domain -->|"persists"| node_postgres
node_kb_domain -->|"persists"| node_postgres
node_kb_domain -->|"retrieves"| node_pgvector
node_backend_infra -->|"wraps"| node_redis
node_backend_infra -->|"stores files"| node_object_storage
node_backend_common -->|"invokes"| node_llm
node_resume_domain -->|"analyzes"| node_llm
node_interview_domain -->|"generates/evaluates"| node_llm
node_kb_domain -->|"rag answers"| node_llm
node_resume_async -->|"streams"| node_redis
node_interview_async -->|"streams"| node_redis
node_kb_async -->|"streams"| node_redis

click node_frontend_app "https://github.com/snailclimb/interview-guide/blob/master/frontend/src/App.tsx"
click node_frontend_api "https://github.com/snailclimb/interview-guide/tree/master/frontend/src/api"
click node_frontend_pages "https://github.com/snailclimb/interview-guide/tree/master/frontend/src/pages"
click node_frontend_components "https://github.com/snailclimb/interview-guide/tree/master/frontend/src/components"
click node_backend_app "https://github.com/snailclimb/interview-guide/blob/master/app/src/main/java/interview/guide/App.java"
click node_backend_common "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/common"
click node_backend_infra "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/infrastructure"
click node_resume_domain "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/resume"
click node_resume_async "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/resume/listener"
click node_interview_domain "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/interview"
click node_interview_async "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/interview/listener"
click node_kb_domain "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/knowledgebase"
click node_kb_async "https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/knowledgebase/listener"

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_frontend_app,node_frontend_api,node_frontend_pages,node_frontend_components toneBlue
class node_backend_app,node_backend_common,node_backend_infra,node_resume_domain,node_resume_async,node_interview_domain,node_interview_async,node_kb_domain,node_kb_async toneAmber
class node_postgres,node_pgvector,node_redis,node_object_storage,node_llm toneRose
```

## Components

### Frontend

React SPA for upload, history, interview, and RAG chat workflows.

- [React SPA](https://github.com/snailclimb/interview-guide/blob/master/frontend/src/App.tsx): client app · Vite + React + TypeScript frontend that consumes REST and streaming APIs. · `frontend/src/App.tsx`
- [API Client](https://github.com/snailclimb/interview-guide/tree/master/frontend/src/api): http/stream client · Typed request modules for resume, interview, history, and RAG chat endpoints. · `frontend/src/api`
- [Pages](https://github.com/snailclimb/interview-guide/tree/master/frontend/src/pages): views · Route-level screens for upload, history, interview, knowledge base management, and query flows. · `frontend/src/pages`
- [UI Components](https://github.com/snailclimb/interview-guide/tree/master/frontend/src/components): ui components · Reusable panels, dialogs, charts, and chat UIs composing the screens. · `frontend/src/components`

### Backend

Spring Boot application with shared platform code and three business domains.

- [Spring App](https://github.com/snailclimb/interview-guide/blob/master/app/src/main/java/interview/guide/App.java): bootstrap · Java 21 / Spring Boot application entrypoint and runtime composition. · `app/src/main/java/interview/guide/App.java`
- [Common Layer](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/common): cross-cutting · Shared error handling, result wrapping, rate limiting, async abstractions, and AI helpers. · `app/src/main/java/interview/guide/common`
- [Infrastructure](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/infrastructure): platform services · File ingestion, PDF export, Redis wrappers, and entity-to-DTO mapping. · `app/src/main/java/interview/guide/infrastructure`
- [Resume Domain](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/resume): business module · Resume upload, parsing, persistence, analysis, history, and deletion. · `app/src/main/java/interview/guide/modules/resume`
- [Resume Jobs](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/resume/listener): async workflow · Redis Stream producer/consumer pair for deferred resume analysis. · `app/src/main/java/interview/guide/modules/resume/listener`
- [Interview Domain](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/interview): business module · Mock interview session creation, question generation, answer capture, grading, and reporting. · `app/src/main/java/interview/guide/modules/interview`
- [Interview Jobs](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/interview/listener): async workflow · Redis Stream producer/consumer pair for answer evaluation and report generation. · `app/src/main/java/interview/guide/modules/interview/listener`
- [Knowledge Base](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/knowledgebase): business module · Document upload, parsing, vectorization, listing, querying, and chat session history. · `app/src/main/java/interview/guide/modules/knowledgebase`
- [Vector Jobs](https://github.com/snailclimb/interview-guide/tree/master/app/src/main/java/interview/guide/modules/knowledgebase/listener): async workflow · Redis Stream producer/consumer pair for embedding generation and vector writes. · `app/src/main/java/interview/guide/modules/knowledgebase/listener`

### External Systems

Datastores, object storage, and AI services used by the backend.

- **PostgreSQL**: relational store · Primary database for resumes, interviews, knowledge base metadata, chat, and analysis records.
- **pgvector**: vector store · Semantic retrieval layer used by the knowledge base query path.
- **Redis**: cache/streams · Cache and session storage plus Redis Stream transport for background jobs.
- **Object Storage**: file store · S3-compatible storage for uploaded source files and generated artifacts.
- **LLM Service**: ai dependency · Spring AI-backed model used through prompt templates and structured DTO outputs.

## Connections

- React SPA → API Client: calls · The SPA uses typed API modules for data access and streaming interactions.
- React SPA → Pages: renders · Route screens compose the user-facing workflows.
- Pages → UI Components: composes · Pages are built from reusable panels and dialogs.
- API Client → Spring App: REST/SSE · Frontend modules communicate with backend controllers via HTTP and streaming endpoints.
- Spring App → Common Layer: shares · Application-wide concerns are handled in common utilities.
- Spring App → Infrastructure: uses · Business modules rely on shared infrastructure services.
- Spring App → Resume Domain: hosts · Resume APIs and services are part of the main Spring application.
- Spring App → Interview Domain: hosts · Interview APIs and services are part of the main Spring application.
- Spring App → Knowledge Base: hosts · Knowledge base and RAG APIs are part of the main Spring application.
- Resume Domain → Resume Jobs: offloads · Resume upload triggers deferred analysis via Redis Stream jobs.
- Interview Domain → Interview Jobs: offloads · Interview evaluation and report generation run asynchronously.
- Knowledge Base → Vector Jobs: offloads · Knowledge base ingestion triggers vectorization jobs asynchronously.
- Resume Domain → PostgreSQL: persists · Resume metadata and analysis records are stored relationally.
- Interview Domain → PostgreSQL: persists · Interview sessions, answers, and reports are stored relationally.
- Knowledge Base → PostgreSQL: persists · Knowledge base records and chat history are stored relationally.
- Knowledge Base → pgvector: retrieves · RAG query flow uses vector search for relevant chunks.
- Infrastructure → Redis: wraps · Shared Redis access powers cache/session state and stream transport.
- Infrastructure → Object Storage: stores files · Uploaded documents and generated artifacts are written to object storage.
- Common Layer → LLM Service: invokes · Shared structured-output AI helper wraps model calls.
- Resume Domain → LLM Service: analyzes · Resume analysis uses prompt-driven structured model output.
- Interview Domain → LLM Service: generates/evaluates · Questions, answer evaluation, and summaries are model-assisted.
- Knowledge Base → LLM Service: rag answers · Query rewriting and answer generation are model-assisted.
- Resume Jobs → Redis: streams · Jobs are published and consumed through Redis Streams.
- Interview Jobs → Redis: streams · Jobs are published and consumed through Redis Streams.
- Vector Jobs → Redis: streams · Jobs are published and consumed through Redis Streams.
