Snailclimb/interview-guide: a Spring Boot 4.1 and Spring AI interview platform you run yourself

What InterviewGuide actually is, and who it is built for

InterviewGuide is a self-hosted platform with five working areas: resume analysis, mock interviews in text and voice, interview scheduling, a RAG knowledge base, and multi-provider model configuration. The README frames it for job seekers, HR staff and training organisations. The realistic audience is narrower. Because the whole thing is a Spring Boot service plus a React front end plus four infrastructure containers, the person who gets value fastest is a Java developer who wants a working reference for Spring AI, pgvector retrieval and Redis Stream task queues, and who is willing to read the code when the documentation stops.

The repository is explicit that every feature is open source and that there will be no paid tier that locks core functionality. A companion tutorial is sold separately, which is worth knowing before you assume the README is the whole story: the README says the tutorial covers infrastructure setup and core business implementation, so some operational detail lives behind a paywall rather than in the repository. The code is AGPL-3.0.

The Redis Stream and pgvector backbone behind the async features

Two infrastructure choices carry most of the architecture. The first is Redis Stream, used as the queue for resume analysis, knowledge base vectorisation and question generation. The README explains the reasoning directly: the author did not want to add Kafka or another full message broker, and Redis Stream also decouples the producers so that analysis and vectorisation could be rewritten in another language later. The visible consequence is that long operations are not synchronous. A resume upload returns quickly, and the UI polls a status that moves through pending, analysing, completed and failed.

The second choice is PostgreSQL with pgvector as both the relational store and the vector store. The README's own FAQ says this is deliberate: PostgreSQL vector storage is considered sufficient, and the goal was to avoid introducing a separate vector database. Retrieval uses query rewriting, a similarity threshold and a TopK strategy, and answers stream to the browser over Server-Sent Events.

Failures are handled per task rather than globally. Resume analysis retries up to three times, and duplicate detection uses a content hash so the same document is not analysed twice. The knowledge base question generator keeps drafts when it cannot produce enough items and shows the actual follow-up count against the target, which avoids silently dropping questions. That kind of detail is more useful than a feature list, because it tells you where the author expected things to go wrong.

Installing InterviewGuide with Docker Compose and running a first resume analysis

The repository ships docker-compose.yml and docker-compose.dev.yml, and the TODO list marks Docker quick deployment as done. The compose file starts PostgreSQL from the pgvector/pgvector:pg16 image with the database interview_guide, Redis 7, and an S3-compatible object store; it mounts ./docker/postgres/init.sql so the schema and the vector extension are created on first boot, and it gates the application container on pg_isready and redis-cli ping health checks. Copy the environment template first, then start the stack:

cp .env.example .env
docker compose up -d

The .env.example file requires two values before anything works: AI_BAILIAN_API_KEY for the DashScope LLM, ASR and TTS services, and APP_AI_CONFIG_ENCRYPTION_KEY, which encrypts provider API keys at rest. The file warns that the encryption key must stay the same after deployment. If you would rather run the backend from Gradle against containerised dependencies, the defaults in .env.example already point at localhost, so you only need the infrastructure services:

docker compose up -d postgres redis
./gradlew bootRun

Optional providers are commented out in the template. Enabling Kimi, DeepSeek or GLM means setting the matching PROVIDER_*_API_KEY and PROVIDER_*_MODEL variables; the file notes that a custom OpenAI-compatible provider also needs a base-url and model entry under app.ai.providers in application.yml. The first real task after login is a resume upload: the README lists PDF, DOCX, DOC, and TXT, parsed with Apache Tika. Expect the record to sit in the analysing state before it reaches completed, because the work happens on the Redis Stream consumer, not in the request thread. The finished report can be exported to PDF through iText 8.

Where the voice interview path falls short

The voice module is the most interesting part of the project and also the part the README is most honest about. It runs over WebSocket with the Qwen3 speech models, and the README claims a 200ms first-packet latency for sentence-level concurrent TTS. It also lists four known problems in a block quote: end-to-end latency is high because audio is relayed through the server, echo leaks when no headset is used, the TTS voice is a single timbre, and audio breaks up on weak networks. The TODO list confirms that WebRTC and additional voices are still open items.

That list should shape your expectations. If your goal is a natural back-and-forth voice interview, this is not it yet; the architecture routes audio through the server rather than negotiating a peer connection. If your goal is to see how streaming ASR, server-side voice activity detection, sentence-level TTS and echo suppression fit together in Spring, it is a useful reference. Two mitigations are exposed as configuration rather than hidden in code. APP_VOICE_ASR_SILENCE_MS controls the silence threshold between ASR segments, and APP_VOICE_USER_UTTERANCE_DEBOUNCE_MS merges multiple STT segments before the interviewer responds. A third flag, APP_VOICE_OPENING_AUDIO_WARMUP_ENABLED, pre-warms the opening audio at startup and is off by default because it calls the cloud TTS service.

How the evaluation engine is shared between text and voice interviews

The design decision worth copying is the unified evaluation engine. Text interviews and voice interviews feed the same pipeline: batch evaluation, structured output, a second aggregation pass, and a fallback path when the model returns something unusable. Because both modes share it, a candidate can compare a text score against a voice score without wondering whether the two were graded differently.

Question generation is driven by SKILL.md files. The README lists more than ten directions, including Java backend, company-specific tracks for Alibaba, ByteDance and Tencent, frontend, Python, algorithms, system design, test development and AI agents. Each file defines the scope, the difficulty distribution and the reference knowledge base. Generation also excludes questions already asked in previous sessions, which matters more than it sounds: without that filter, repeated practice sessions converge on the same handful of prompts.

The knowledge base question bank adds a harder constraint. Before a session starts, the system computes available capacity from the direction, difficulty, main question count and follow-up count per question, and disables options that cannot be satisfied; the README notes that follow-up count is a hard constraint and that the backend validates it as well. That is a real design choice with a real cost: you cannot start a session that the bank cannot fill, so a thin question bank limits what you can practise.

When to choose a hosted product or a Python RAG stack instead

The obvious alternative for a job seeker is a hosted interview practice product, and the difference is operational rather than functional. A hosted product gives you a question bank and speech models without a PostgreSQL container, a Redis container, an object store, an API key for a Chinese cloud provider and a JDK 25 toolchain. InterviewGuide gives you the data: resumes, transcripts, evaluation reports and vectorised documents stay on your infrastructure, and you can change the model provider from the settings page instead of filing a support request.

On the engineering side, the alternative is a Python RAG stack built from LlamaIndex or LangChain with a dedicated vector database. That path has more retrieval libraries and more examples, and it does not require pgvector. InterviewGuide's counter-argument is in its own FAQ: keeping vectors in PostgreSQL means one fewer component to run, and the Redis Stream queue means one fewer broker. Whether that trade is right depends on your team. A Java team that already runs PostgreSQL and Redis gets a short path to a working system. A team with no JVM experience and no interest in Gradle will spend its first week on toolchain problems rather than on retrieval quality.

Licence, upgrade cost and what the README does not cover

InterviewGuide is licensed under AGPL-3.0. That matters if you plan to offer it as a network service: the licence's network clause is the reason many teams treat AGPL projects as internal tools or as reading material rather than as a base for a closed product. This is not legal advice, and the specific obligations depend on how you deploy and modify it, so read the LICENSE file and get your own answer.

The upgrade surface is wide. The README pins Spring Boot 4.1.0, Java 25, Spring AI 2.0.0, Spring AI Agent Utils 0.10.0, Gradle 9.6.1, PostgreSQL 14 or later, Redis 6 or later with Redisson 4.0.0, Apache Tika 2.9.2, iText 8.0.5, MapStruct 1.6.3 and SpringDoc OpenAPI 3.0.2. Java 25 and Spring Boot 4.1 are both recent, so you are tracking fast-moving upstreams rather than a conservative baseline; expect to re-test the AI integration whenever Spring AI changes its APIs. The runtime configuration adds its own constraint: settings are written to ~/.interview-guide/ in the user directory, and provider API keys are encrypted with APP_AI_CONFIG_ENCRYPTION_KEY, which the template says must remain unchanged after deployment. Lose or rotate that key without a migration plan and the stored provider credentials become unreadable.

The repository carries no release entries, so there is no changelog to read before upgrading. The last push was on 2026-08-14, which is recent enough that the project is moving, but the README does not document a rollback procedure, a migration path for the encrypted config file, or a versioned API contract for the frontend.

Editorial conclusion

Adopt InterviewGuide if you want one Java service that covers resume analysis, text and voice mock interviews, scheduling and a pgvector knowledge base, and you are prepared to run PostgreSQL with pgvector, Redis and an S3-compatible store yourself. Skip it if you need low-latency conversational voice, a licence that permits closed-source redistribution, or a stack that runs on the current LTS JDK. Before committing, check that your JDK and Gradle versions match the README table, that PostgreSQL is at 14 or later, and that you have replaced the placeholder values in .env.example, including APP_AI_CONFIG_ENCRYPTION_KEY.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. Snailclimb/interview-guide on GitHub