Functional Specification¶

Documentation of the Recron system features — a tool for interview preparation and job search management.

Implemented Features¶

Platform & Infrastructure¶

Authentication (Keycloak OIDC)¶

Secure login via the OpenID Connect protocol with Authorization Code + PKCE flow. The system automatically refreshes tokens and requires authentication for all protected resources. Username is displayed in the UI.

Access Control (RBAC)¶

Three permission levels managed in Keycloak:

User — browse questions, vote, learning list, propose questions, manage own offers, manage portfolio
Moderator — additionally approve/reject proposed questions
Admin — full system management access

The frontend hides actions not permitted for the current role.

Dark Mode¶

Light/dark toggle in the navigation bar. Preference is saved in localStorage and restored on subsequent visits.

Internationalization (i18n)¶

Support for Polish and English languages. Language switcher in the UI, all strings via translation keys, preference is persisted.

User Profile¶

Editable user profile stored in the Users.Api database. Includes:

Field	Type	Description
displayName	string	Display name
bio	string?	Short biography
preferredRole	string?	Preferred job role (e.g. .NET Dev)
experienceYears	int?	Years of professional experience
location	string?	City or region
skills	string?	Comma-separated skill list
linkedInUrl	string?	LinkedIn profile URL
gitHubUrl	string?	GitHub profile URL
websiteUrl	string?	Personal website URL

Profile data is used by features such as AI CV-to-offer matching and can be extended for future personalization.

Interview Questions Module¶

Hierarchical Categories¶

Questions organized in a tree structure of categories (e.g. .NET → Entity Framework → Migrations). Categories have a name, optional description, and icon. Displayed in a defined order.

Question Management¶

Authenticated users can propose new questions (status "Pending"). Moderators approve (→ "Approved", visible to everyone) or reject (→ "Rejected", hidden). Author tracked via the CreatedBy field. Edit question content and answers. Delete questions.

Voting (Promote)¶

Question voting system — one vote per user per question (toggle). Displays vote count (PromoteCount) and whether the current user has voted.

Learning List¶

Personal list of questions to study. Add/remove questions, isolated per user, persisted across sessions.

AI Answers¶

AI-generated answers based on the question content and category context. Saved in the Description field, supports markdown rendering, shows a loading indicator.

Question Ordering¶

The Order field determines display position. Move questions up/down within a category. New questions are added at the end of the list.

Question Filtering¶

Filter questions by status: all, promoted (most voted), and learning list. Enables quick access to the most relevant questions.

Quiz / Flashcards¶

Interactive study mode using questions from the user's learning list.

Setup:

Select category (optional — all categories by default)
Choose question count (1–100, default 20)
Only questions with approved answers (non-empty Description) are included

Session:

Flashcard UI with flip animation — front shows question, back shows answer (markdown rendered)
Navigate between cards (previous/next)
Mark cards as "known" or "to review"
Progress bar showing completion

Summary:

Total questions reviewed
Count of known vs. to-review items
Option to restart or return to questions

Recruitment Organizer Module¶

Job Offers¶

Track job applications with full context. Each user sees only their own offers. List interface with drag & drop to reorder.

Basic fields (visible in the list):

Field	Type	Required	Description
name	string	✓	Job title
companyName	string	✓	Company name
status	enum	✓	Recruitment process status
link	string		URL to job posting
city	string		City

Detail fields (visible in offer details):

Field	Type	Description
source	enum	LinkedIn, NoFluffJobs, JustJoinIT, Pracuj, Email, Direct, Other
workMode	enum	Remote, Hybrid, Onsite
intermediary	string	Recruitment agency (if applicable)
salaryMin/Max	decimal	Salary range
salaryCurrency	enum	PLN, EUR, USD
salaryType	enum	Monthly, Hourly, Annual
description	string	Notes (supports markdown)
reasons	string[]	Rejection/interest reasons
isAiGenerated	bool	Whether the offer was created via AI parsing
rawContent	string?	Original content used for AI parsing
sourceUrl	string?	Original URL of the job posting

List functionality:

Filter by status (primary filter)
Drag & drop to reorder within a status
Default sort by date added (newest at the bottom)
Basic list actions: change status, open link, delete
Click an offer → detail drawer with tabs (Timeline, Details, Match CV)

Business rules:

New offers are always created with status New
Changing status to New automatically clears the reasons field
The Order field determines position in the list (per status)

Offer Statuses¶

Track application progress throughout the recruitment process.

Status	Meaning	Color
New	New, not yet applied	Gray
Considered	Under consideration, analyzing the offer	Blue
Sent	Application sent	Orange
Rejected	Rejected (by the company or by me)	Red

Functionality:

Arbitrary status changes (non-linear flow)
Filter and group by status
Status counters in the UI

AI Offer Parsing¶

Create job offers automatically using AI analysis. Two input modes:

Parse from URL:

User provides a job posting URL
AI fetches the page content and extracts structured offer data
Pre-fills all offer fields (name, company, city, salary, work mode, source, etc.)
User reviews and confirms or edits before saving

Parse from pasted text:

User pastes raw job offer description
AI analyzes the text and extracts the same structured data
Same review-and-confirm flow

Manual entry is also available as a third option in the wizard.

The wizard UI guides the user through mode selection → input → review → save.

Offer Duplication¶

One-click duplication of existing offers. Creates a full copy of the offer with all fields preserved. Useful when applying to similar positions or tracking reposted offers.

Interview Stages¶

Recruitment process timeline displayed in offer details. Vertical timeline with icons for stage types, built with CSS Modules.

Stage fields:

Field	Type	Required	Description
stage	enum	✓	Stage type
status	enum	✓	Stage status
scheduledAt	DateTimeOffset		Date and time
duration	int		Duration (minutes)
location	string		Location or meeting link
notes	string		Notes (supports markdown)

Types (stage): Screening, Technical, HR, Offer, Onboarding

Statuses: Scheduled, Completed, Failed, Cancelled

Timeline sorting:

Stages with a date — sorted chronologically at the top
Stages without a date — sorted by natural type order (Screening → Technical → HR → Offer → Onboarding)

Functionality:

CRUD operations for stages in the offer detail view
Displayed as a vertical timeline with icons
No drag & drop (static timeline)
Different icons for each stage type
Markdown editing for interview notes via dedicated editor dialog with live preview

Post-Interview Notes (Markdown)¶

Interview notes support full markdown editing:

Dedicated markdown editor dialog with split-pane view (editor + live preview)
Notes display rendered as markdown in the interview card (with fade-out truncation for long content)
Available in both "Add interview" and "Edit interview" flows
Uses the shared MarkdownEditDialog component

Google Calendar Integration¶

Full OAuth2-based integration with Google Calendar API.

Connect/disconnect Google Calendar in Settings
Automatic creation of calendar events when scheduling interviews
Automatic update/deletion of events when interviews are modified or removed
CalendarEventId stored on interview stages for sync tracking
OAuth2 flow with token refresh and secure storage

Statistics Dashboard¶

Analytics dashboard for the recruitment process.

Summary cards:

Total offers count
Total interviews count
Conversion rate (interviews / offers as percentage)
Average salary range (when salary data available)

Charts:

Breakdown by status (colored chips)
Breakdown by source (horizontal bar chart)
Breakdown by work mode (horizontal bar chart)
Breakdown by interview stage (horizontal bar chart)
Weekly application activity (vertical bar chart with date labels)

AI CV-to-Offer Matching¶

AI-powered analysis of how well a user's CV matches a specific job offer.

Flow:

User opens offer details → "Match CV" tab
Selects a CV variant (if multiple exist)
AI analyzes the CV against the offer requirements
Results displayed with:
Match score (0–100) shown as an animated SVG ring
Summary — overall assessment
Strengths — matching qualifications
Gaps — missing requirements
Recommendations — suggestions to improve the match

Technical:

Uses IChatClient (OpenAI) with structured prompts
Sends both offer data (from DB) and portfolio data (from request)
AI responds in Polish with JSON structure
Frontend: MatchCvPanel component in the offer drawer's third tab

Offer Tagging¶

Categorize offers with custom user-defined tags for flexible organization.

Tag entity with name and color (HEX)
User-scoped tags (each user manages their own set)
Assign multiple tags to any offer
Filter offers by tags in the list view
Unique tag names per user enforced at database level

Cover Letter Generator¶

AI generates a personalized cover letter based on the user's portfolio and a specific job offer.

Select tone: formal, creative, concise
Uses offer data + portfolio content (strengths, gaps, recommendations) to craft a targeted letter
Markdown rendering of generated letter with copy support
Accessible from the offer drawer as a dedicated tab
Reuses existing IChatClient infrastructure and portfolio data model

Offer Comparison Matrix¶

Side-by-side AI-powered comparison of selected offers across key criteria.

User selects 2–5 offers to compare
AI analyzes offers across multiple dimensions: salary, requirements, growth potential, work-life balance
Visual presentation with radar chart
Ranked recommendation with explanation
Accessible from the offers list via multi-select action

AI Offer Scoring (Offer Radar)¶

Automatic AI scoring of job offers against the user's profile. Proactive compatibility assessment.

AI analyzes offer requirements vs. user's profile (skills, experience, preferred role, location)
Match score (0–100) persisted on the offer entity
Score breakdown explaining why the offer fits or doesn't
Dedicated tab in offer drawer with score visualization
Uses inter-service communication to fetch user profile from Users.Api

Dictionaries (Enums)¶

Predefined values for data consistency:

Source, WorkMode, Currency, SalaryType
StepType, StepStatus, OfferStatus

Endpoint to fetch values, i18n translations, UI Select/Autocomplete.

CV Portfolio Module¶

Full-featured CV builder with multiple variants and AI-powered import.

CV Data Model¶

Each portfolio contains structured sections:

Section	Fields
Personal Info	firstName, lastName, email, phone, location, linkedIn, website
Summary	Professional summary text
Experience	company, position, startDate, endDate, current, description
Projects	name, description, technologies[], link
Skills	name, level (Beginner / Intermediate / Advanced / Expert)
Education	institution, degree, field, startDate, endDate
Certifications	name, issuer, date, link
Languages	name, level (A1 / A2 / B1 / B2 / C1 / C2 / Native)

Multiple CV Variants¶

Users can create and manage multiple CV variants (e.g. "Backend Developer", "Full-Stack", "DevOps"). Each variant is a complete portfolio with its own name and data. Variant selector in the UI allows quick switching.

CV Preview Templates¶

Three visual templates for CV preview:

Default — clean single-column layout
Burgundy — styled with burgundy color accents
Two-column — sidebar + main content layout

AI Import¶

From LinkedIn URL:

User provides their LinkedIn profile URL
AI fetches and parses the profile data
Auto-populates all CV sections from LinkedIn data

From PDF upload:

User uploads an existing CV in PDF format
AI extracts structured data from the document
Auto-populates all CV sections from the parsed PDF

CV Export¶

Download CV in multiple formats directly from the preview tab:

PDF — generated client-side via html2pdf.js, A4 format, works with all 3 templates
HTML — standalone HTML file with embedded styles
JSON — raw portfolio data for backup or external use

Auto-save¶

Portfolio changes are automatically saved with debounce. localStorage fallback ensures no data loss during network issues.

Future Extensions¶

Short-term (Low Effort)¶

Extended Offer Statuses¶

Current statuses (New, Considered, Sent, Rejected) do not cover the full recruitment funnel. Missing positive outcomes after application.

Add new statuses: InterviewScheduled, OfferReceived, Accepted, Withdrawn
Enables tracking the complete pipeline from discovery to job acceptance
Unlocks accurate funnel conversion metrics (e.g. sent → interview → offer → accepted)
Color-coded in UI: InterviewScheduled (Purple), OfferReceived (Green), Accepted (Emerald), Withdrawn (Gray)
Backward compatible — existing offers remain valid

ATS Compatibility Checker (AI)¶

AI analyzes the user's CV against Applicant Tracking System (ATS) best practices. Most companies use ATS software to filter resumes before a human reviews them — up to 75% of CVs are rejected at this stage.

User selects a CV variant to check
AI evaluates: keyword density, formatting compatibility, section structure, length, actionable language
Score (0–100) with category breakdown (e.g. keywords: 80, formatting: 60, structure: 90)
Specific recommendations: "Add keyword X from the job description", "Avoid tables — ATS cannot parse them"
Optional: check against a specific offer's requirements for targeted optimization
Accessible from the Portfolio page as a dedicated action per CV variant

Question Difficulty Levels¶

Add difficulty classification to interview questions for targeted study.

Difficulty enum: Junior, Mid, Senior
Displayed as a badge on each question
Filter questions by difficulty level
Combined with category filter for precise study targeting (e.g. "Senior .NET questions about EF Core")
Difficulty suggested by AI when proposing or approving questions

Technology Tags on Questions¶

Complement the hierarchical category system with cross-cutting technology tags.

Tag questions with specific technologies (e.g. React, .NET, SQL, Docker)
Multiple tags per question
Filter by technology across categories
AI-powered: "Show questions relevant to offer X" — matches offer requirements to question tags
Helps users prepare for specific tech stacks required by target offers

STAR Method Assistant¶

Structured tool for preparing behavioral interview answers using the STAR framework (Situation, Task, Action, Result).

Template-based editor: user fills in each STAR component separately
Library of common behavioral questions (e.g. "Tell me about a time you handled conflict")
AI assistance: takes user's raw experience description and restructures it into STAR format
Saved per user — builds a personal library of prepared behavioral answers
Can link STAR stories to specific offers or interview stages

Thank You Note Generator¶

AI generates professional post-interview thank-you notes.

Input: interview details (company, position, interviewer name, topics discussed)
AI generates a personalized thank-you email
Tone options: formal, warm, enthusiastic
Available from the interview timeline after marking a stage as completed
Markdown preview with copy-to-clipboard

Medium-term (Moderate Effort)¶

AI Interview Coach (Mock Interview)¶

AI-powered interactive interview simulation. The AI conducts a realistic interview tailored to the user's target position and experience level.

User selects mode: Technical, Behavioral, System Design, or HR
User selects category/position or links to a specific offer
AI asks questions one by one, waits for user's text answer
AI evaluates each answer: correctness, completeness, communication clarity
Real-time feedback after each question with suggestions for improvement
Session summary: overall score, strong areas, knowledge gaps, recommended questions to study
Integration with Questions module — suggested questions auto-added to learning list
Integration with Organizer — can prepare for a specific offer's interview
Conversation history saved for review
New page: /mock-interview

Spaced Repetition Learning (SM-2 Algorithm)¶

Replace random quiz selection with scientifically proven spaced repetition for long-term knowledge retention.

Implement the SM-2 algorithm (SuperMemo 2) on the learning list
New fields on LearningQuestionEntity: EaseFactor, Interval, NextReviewDate, RepetitionCount, LastGrade
After each quiz answer, user grades difficulty (0–5 scale), which adjusts the review schedule
Questions due for review surface automatically — no manual selection needed
Dashboard widget: "X questions due for review today"
Learning analytics: retention rate over time, mastery per category, streak tracking
Significantly improves knowledge retention compared to random flashcards (proven 90%+ recall vs ~30%)

CV Variants per Offer (AI-Suggested Tailoring)¶

Automated CV tailoring recommendations linked to specific job offers.

Link a CV variant to a specific offer in the Organizer
AI analyzes the offer requirements and suggests: which skills to highlight, which experience to emphasize, which sections to reorder
One-click "Create tailored variant" from offer drawer — duplicates an existing CV and applies AI suggestions
Side-by-side diff view: original CV vs. tailored version
Reuses existing portfolio variant system — no new data model needed
Tailored CVs increase callback rate by 30–50%

Salary Insights & Negotiation Helper¶

Aggregated salary analytics from the user's tracked offers, combined with AI-powered negotiation advice.

Dashboard visualizations: salary trends over time, medians by city/source/work mode/position
"My expectations vs. my offers" comparison chart
AI negotiation advisor: based on profile, offer data, and market context, suggests salary range and negotiation arguments
Negotiation script generator: AI produces specific talking points, counter-offer templates, and responses to common employer objections
Triggered from offers with status OfferReceived — "Prepare negotiation strategy"
Export salary report as PDF
Requires sufficient user data for meaningful insights (minimum threshold indicator)

Skill Gap Analysis & Learning Paths¶

AI cross-references requirements from the user's tracked offers with skills from their portfolio to identify competency gaps.

Aggregated skill demand: "these skills appear most frequently in your offers"
Gap detection: "these skills are required but missing from your CV"
Priority ranking: which gaps to close first (based on frequency and offer match impact)
Integration with Questions module — auto-suggest relevant questions to add to learning list
Integration with Portfolio — highlight which CV sections to strengthen
Learning resource suggestions (optional: links to documentation, courses)

Application Timeline & Reminders¶

Proactive notification and reminder system for the recruitment process.

Upcoming interview reminders (configurable: 1 day, 1 hour before)
Follow-up reminders: "You sent an application to Company X 7 days ago — follow up?"
Stale offer alerts: "Offer Y has been in 'New' status for 14 days — review or archive?"
Full application timeline view per offer: every status change, interview, and action on a visual timeline
Configurable notification preferences (in-app, email — future)
Requires background job infrastructure (e.g. Hangfire or .NET Aspire worker)

Networking & Contact Tracker (Recruiter CRM)¶

Mini-CRM for tracking recruitment contacts and networking interactions.

Contact entity: name, company, role (recruiter/hiring manager/referral), email, phone, LinkedIn, notes
Link contacts to offers and interviews ("this recruiter is handling Offer X")
Interaction history: log calls, emails, messages with timestamps
Follow-up reminders per contact ("You haven't contacted Jan from Company X in 30 days")
AI-generated follow-up message templates
Network visualization: which contacts connect to which offers
New microservice or extension of Organizer.Api

Long-term (High Effort)¶

Status Change History (Activity Log)¶

Audit trail of offer status changes with timestamps, providing full recruitment process visibility.

New entity OfferActivityEntity: OfferId, FromStatus, ToStatus, Timestamp, Note
Full timeline view per offer: every status change, interview, and action
Analytics: average time spent in each status, bottleneck detection
"Time in pipeline" metric per offer and aggregate

Attachments¶

Store documents with offers (JD, CV, screenshots). Supported formats: PDF, PNG, JPG, DOCX, TXT. Limits: 10 files/offer, 5MB/file.

Shared Question Sets & Community¶

Allow users to share curated question sets with others. Extends the existing propose/approve/vote system toward a community platform.

Public question packs (e.g. "Frontend Senior — 50 questions", ".NET Mid — 40 questions")
User-created collections with export/import
Rating and reviews for shared sets
Community leaderboard: top contributors, most popular sets
Moderation tools for community content

Multi-language CV Generation¶

AI translates portfolio content into other languages with market-specific adjustments.

Supported languages: EN ↔ PL, DE, FR (extensible)
Not just translation — AI adapts CV style to target market conventions (e.g. German CVs include photo, date of birth)
Per-language CV variants stored alongside existing variant system
Integration with Cover Letter Generator — generate letters in the target language

Multi-language AI Responses¶

AI-generated answers and CV matching in the user's preferred language (currently Polish-only for some features). Language selection for AI features independent of UI language.

Interview Notes & Question Bank per Offer¶

Bridge between the Organizer and Questions modules — log interview questions encountered during actual interviews.

After an interview, user logs questions that were asked
Questions auto-suggested for addition to the Questions bank (with company/position context)
Pattern recognition: "FAANG companies ask about X, startups ask about Y"
Per-company question history: "last time at Company Z they asked about..."
Builds a personalized intelligence database over time

Advanced Funnel Analytics¶

Extended recruitment analytics beyond the current dashboard.

Full conversion funnel: offers → applications → interviews → offers received → accepted
Time-to-response tracking: average days from application to first response
Month-over-month comparison: "this month vs. last month"
Goal tracking: "I want to receive an offer by March 31" with progress indicator
Exportable reports (PDF, CSV)
Predictive insights: "based on your current pace, you'll likely receive an offer by..."
Requires Extended Offer Statuses to be implemented first for full funnel visibility

Career Path Planner¶

Long-term career development companion that extends Recron beyond job search into ongoing career management.

Skills gap analysis based on desired role vs. current profile
AI-generated roadmap: "To transition from Mid to Senior .NET Dev, focus on: system design, mentoring, architecture patterns"
Recommended certifications and learning resources per career goal
Market demand tracking: which technologies are trending up/down based on offer data
Progress tracking over time: skill acquisition milestones
Integration with Portfolio — automatically suggest CV updates as skills grow

Job Market Scanner (Automated Search)¶

Passive job discovery — the system works for the user in the background.

User defines saved search criteria: role, city, salary range, technologies, work mode
System periodically scans job sources (JustJoinIT API, NoFluffJobs API, LinkedIn Jobs)
Matching offers auto-added to Organizer with status New and AI pre-scoring
Daily/weekly digest email with new matches
Deduplication: don't add offers the user already tracks
Requires significant infrastructure: scheduled workers, API integrations, rate limiting
Transforms Recron from a tracking tool into a proactive career companion