How snailclimb/interview-guide works
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.java Spring App · knowledgebase Knowledge Base · resume Resume Domain · interview Interview Domain
Components 18
Frontend
React SPA for upload, history, interview, and RAG chat workflows.
- React SPA · Vite + React + TypeScript frontend that consumes REST and streaming APIs.
frontend/src/App.tsx - API Client · Typed request modules for resume, interview, history, and RAG chat endpoints.
frontend/src/api - Pages · Route-level screens for upload, history, interview, knowledge base management, and query flows.
frontend/src/pages - 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 · Java 21 / Spring Boot application entrypoint and runtime composition.
app/src/main/java/interview/guide/App.java - Common Layer · Shared error handling, result wrapping, rate limiting, async abstractions, and AI helpers.
app/src/main/java/interview/guide/common - Infrastructure · File ingestion, PDF export, Redis wrappers, and entity-to-DTO mapping.
app/src/main/java/interview/guide/infrastructure - Resume Domain · Resume upload, parsing, persistence, analysis, history, and deletion.
app/src/main/java/interview/guide/modules/resume - Resume Jobs · Redis Stream producer/consumer pair for deferred resume analysis.
app/src/main/java/interview/guide/modules/resume/listener - Interview Domain · Mock interview session creation, question generation, answer capture, grading, and reporting.
app/src/main/java/interview/guide/modules/interview - Interview Jobs · Redis Stream producer/consumer pair for answer evaluation and report generation.
app/src/main/java/interview/guide/modules/interview/listener - Knowledge Base · Document upload, parsing, vectorization, listing, querying, and chat session history.
app/src/main/java/interview/guide/modules/knowledgebase - Vector Jobs · 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 · Primary database for resumes, interviews, knowledge base metadata, chat, and analysis records.
- pgvector · Semantic retrieval layer used by the knowledge base query path.
- Redis · Cache and session storage plus Redis Stream transport for background jobs.
- Object Storage · S3-compatible storage for uploaded source files and generated artifacts.
- LLM Service · Spring AI-backed model used through prompt templates and structured DTO outputs.
Connections 25
- 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.