Forem: Pete Letkeman

AI-Powered Resume Generator: Architecture & Implementation

Pete Letkeman — Sat, 24 Jan 2026 01:18:09 +0000

Building an AI-Powered Resume Generator: Architecture & Implementation

Overview

I've been working on a full-stack application that leverages LLMs to generate polished, professional resume content. This post is a technical walkthrough of the architecture, integration points, and key implementation details.

Tech Stack:

Backend: Java 21, Spring Boot 3.x, Gradle
Frontend: React 19, TypeScript, Vite
LLM Integration: OpenAI API / Ollama (OpenAI-compatible endpoint)
Data Format: JSON-driven resume model
Build Tooling: Gradle (backend), Node (frontend)

Repository: https://github.com/pbaletkeman/java-resumes

Architecture Overview

┌─────────────┐
│   React UI  │
│ (TypeScript)│
└──────┬──────┘
       │ HTTP/REST
       ↓
┌─────────────────────────────────┐
│   Spring Boot REST API          │
│  (Java 21, Gradle 8.10)         │
│                                 │
│  ├─ ResumeController            │
│  ├─ FilesStorageService         │
│  └─ ApiService (LLM gateway)    │
└──────────┬──────────────────────┘
           │
      ┌────┴─────┐
      ↓          ↓
  ┌────────┐  ┌────────────┐
  │ Ollama │  │ OpenAI API │
  │(local) │  │  (cloud)   │
  └────────┘  └────────────┘

Key Components & Design Decisions

1. REST API Layer (Spring Boot)

The backend exposes endpoints for:

File uploads (multipart/form-data)
Resume optimization (async background processing)
File retrieval (results polling)
File management (list, download, delete)

Key Endpoint Pattern:

@PostMapping(path = "/api/upload")
public ResponseEntity<ResponseMessage> optimizeResume(
    @RequestParam("optimize") String optimizeJson,
    @RequestParam("resume") MultipartFile resume,
    @RequestParam("job") MultipartFile job) {

    // Validate inputs
    if (resume.isEmpty() || job.isEmpty()) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
            .body(new ResponseMessage("No file/invalid file provided"));
    }

    // Spawn background thread for LLM processing (non-blocking)
    Thread thread = new Thread(new BackgroundResume(optimize, root));
    thread.start();

    // Return 202 Accepted immediately
    return ResponseEntity.status(HttpStatus.ACCEPTED)
        .body(new ResponseMessage("generating"));
}

Why this pattern?

LLM API calls are slow (2-30+ seconds)
HTTP connections timeout if we wait for LLM
202 Accepted signals async processing to the client
Frontend polls /api/files until results appear

2. Async Background Processing

The BackgroundResume class handles long-running operations:

public class BackgroundResume implements Runnable {
    private final Optimize optimize;
    private final String root;

    @Override
    public void run() {
        try {
            // 1. Load LLM configuration
            String configStr = Utility.readFileAsString("config.json");
            Config config = new Gson().fromJson(configStr, Config.class);

            // 2. Build LLM request
            ChatBody chatBody = ApiService.createChatBody(optimize);

            // 3. Call LLM (OpenAI-compatible API)
            LLMResponse response = ApiService.produceFiles(
                optimize,
                config.getEndpoint(),
                config.getApikey(),
                config.getModel()
            );

            // 4. Save results (Markdown + PDF)
            FilesStorageService.save(response.getContent());

            LOGGER.info("Resume optimization completed");
        } catch (Exception e) {
            LOGGER.error("Background task failed: {}", e.getMessage());
        }
    }
}

Why background threads instead of async/await?

Simple, synchronous model
No need for reactive framework overhead
Easy to reason about error handling
Works well for moderate concurrency

3. LLM Integration (OpenAI-Compatible API)

The ApiService class abstracts LLM provider differences:

public class ApiService {
    public static LLMResponse produceFiles(
        Optimize optimize,
        String endpoint,
        String apiKey,
        String model) throws Exception {

        // Build OpenAI-compatible request
        ChatBody chatBody = new ChatBody();
        chatBody.setModel(model);
        chatBody.setMessages(createPrompt(optimize));
        chatBody.setTemperature(optimize.getTemperature());

        // Send to LLM
        HttpClient client = HttpClient.newHttpClient();
        String jsonRequest = new Gson().toJson(chatBody);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint + "/v1/chat/completions"))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonRequest))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        // Parse response
        LLMResponse llmResponse = new Gson().fromJson(
            response.body(),
            LLMResponse.class
        );

        return llmResponse;
    }
}

Why OpenAI-compatible format?

Works with Ollama (local models)
Works with OpenAI (cloud models)
Works with Azure OpenAI, Together.ai, etc.
Single integration code path
Easy to swap providers

Configuration (config.json):

{
  "endpoint": "http://localhost:11434",
  "apikey": "ollama",
  "model": "mistral:7b"
}

Frontend Architecture (React + TypeScript)

Core Hook: `useApi`

Centralized API communication:

export function useApi() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const execute = async (fn: () => Promise<any>) => {
    setLoading(true);
    setError(null);
    try {
      await fn();
    } catch (err) {
      setError(err instanceof Error ? err.message : "Unknown error");
      throw err;
    } finally {
      setLoading(false);
    }
  };

  return { execute, loading, error };
}

File Upload & Polling Pattern

function MainContentTab() {
  const { execute, loading } = useApi();
  const [generatedFiles, setGeneratedFiles] = useState<File[]>([]);

  const handleSubmit = async (formData: FormData) => {
    await execute(async () => {
      // 1. Upload resume + job description
      await fileService.uploadForOptimization(formData);

      // 2. Start polling for results
      let attempts = 0;
      while (attempts < 60) { // 5 minutes max
        await new Promise(r => setTimeout(r, 5000)); // Poll every 5s

        const files = await fileService.listFiles();
        const newFiles = files.filter(f =>
          f.name.endsWith('.pdf') &&
          f.timestamp > formData.get('uploadTime')
        );

        if (newFiles.length > 0) {
          setGeneratedFiles(newFiles);
          break;
        }
        attempts++;
      }
    });
  };

  return (
    // UI for upload and display results
  );
}

Why polling instead of WebSockets?

Simpler client/server contract
Works through corporate proxies/firewalls
No need for persistent connection
Acceptable for batch processing workflows

Data Model: Optimize DTO

public class Optimize {
    private String[] promptType;      // ["Resume", "CoverLetter", "Skills"]
    private double temperature;        // 0.0-1.0 (creativity level)
    private String model;              // Model identifier from config
    private String company;            // Target company name
    private String jobTitle;           // Target job title
    private String jobDescription;     // Full job posting text
    private String resume;             // User's current resume

    // Getters/setters...
}

This DTO drives:

Prompt construction - What content to generate
LLM parameters - Temperature, model selection
Output filtering - Which sections to include

Key Implementation Challenges & Solutions

Challenge 1: LLM Response Time

Problem: API calls can take 10-30+ seconds
Solution:

Return 202 Accepted immediately
Process async in background thread
Frontend polls for completion

Challenge 2: File Format Conversion

Problem: LLM outputs plain text; need PDF with formatting
Solution:

Convert Markdown → HTML (CommonMark parser)
Convert HTML → PDF (Flying Saucer library)
Save both Markdown + PDF for flexibility

Challenge 3: Local vs Cloud LLM

Problem: Different APIs for Ollama vs OpenAI
Solution:

Use OpenAI-compatible format (both support it)
Config-driven endpoint selection
Single integration point

Challenge 4: Test Isolation

Problem: Tests failing due to state dependencies (file existence)
Solution:

@BeforeEach
void setUp() throws IOException {
    Path uploadsPath = Paths.get("uploads");
    Files.createDirectories(uploadsPath);
    // Create dummy files for delete tests, etc.
    Files.write(uploadsPath.resolve("resume.pdf"),
        "dummy".getBytes());
}

Deployment Considerations

Local Development

# Terminal 1: Start Ollama
ollama serve
ollama pull mistral:7b

# Terminal 2: Run backend
./gradlew bootRun  # Listens on :8080

# Terminal 3: Run frontend
cd frontend && npm run dev  # Listens on :5173

Cloud Deployment

# application.properties
server.port=8080
upload.path=/data/uploads
# Spring will detect OpenAI config from environment

Testing Strategy

80%+ Coverage Target:

Controller Tests - HTTP layer with MockMvc
Service Tests - Business logic, mocked LLM
Integration Tests - Full request flow
Model Tests - DTO serialization/validation

./gradlew test                    # Run all tests
./gradlew test --tests ClassName  # Run specific test
./gradlew checkstyleMain          # Code quality (100% compliance)

Performance & Scalability Notes

Horizontal Scaling: Add more backend instances behind load balancer
Rate Limiting: Implement per-user quotas for LLM API costs
Caching: Cache LLM responses for identical inputs
Async Queue: For high volume, use message queue (RabbitMQ, Kafka)
File Storage: Consider cloud storage (S3, Azure Blob) vs local filesystem

⚠️ Important Considerations

LLM Hallucination Risk

Critical: LLMs can generate plausible-sounding but inaccurate content. This includes:

Fabricated job experiences
Incorrect technical skills
Made-up company names or achievements
Dates and timelines that don't align with reality

Mitigation:

Always proofread generated content before using it
Cross-check facts against source documents
Verify all claims in the resume
Consider this tool as a content enhancement tool, not a replacement for human review
Use it to refine and polish verified information, not to generate unverified content

Processing Time

Important: File generation is NOT instant:

Local models (Ollama): 30 seconds to 5+ minutes depending on model size (7B models are faster, 13B+ models take longer)
Cloud models (OpenAI): 5-30 seconds typically, but can vary with load
Large job descriptions: Processing time increases with input size
Network latency: Slower connections add to total time

Frontend Polling:

// Default: polls every 5 seconds for up to 5 minutes (60 attempts)
// For longer processing, increase attempts or polling interval
let attempts = 0;
while (attempts < 60) {
  // Adjust this for longer waits
  await new Promise((r) => setTimeout(r, 5000)); // 5 seconds
  // ... check for files
  attempts++;
}

User Experience:

Display a progress indicator during processing
Show estimated wait time based on model selection
Allow users to check back later via job ID
Consider implementing email notifications when complete

Code Quality Standards

Checkstyle: 100% compliance (120 char line limit)
Test Coverage: 80%+ target
Java Version: Java 21 LTS with modern features
Spring Boot: Version 3.5.1 with latest practices

What's Next?

Potential improvements:

[ ] WebSocket support for real-time updates
[ ] Template system for different resume formats
[ ] Batch processing for multiple candidates
[ ] Integration with LinkedIn/job boards
[ ] A/B testing for LLM prompt optimization
[ ] Cost analytics for OpenAI usage

Lessons Learned

Async by Default - HTTP endpoints should never block on slow operations
Embrace Standards - OpenAI-compatible API is a superpower
Simple Patterns > Complex Frameworks - Background threads work great for this use case
Test Independence - Always set up required state in @BeforeEach
Config Over Code - Keep LLM provider flexible via configuration

Get Started

Repository: https://github.com/pbaletkeman/java-resumes

Quick Start:

git clone https://github.com/pbaletkeman/java-resumes
cd java-resumes
./gradlew clean build
./gradlew bootRun
# Visit http://localhost:8080/spotlight/index.html

Credits

Special thanks to Shaw Talebi for his excellent tutorial on building resume optimization tools, which served as the inspiration and starter foundation for this project.

Have you built LLM integrations in Java? What patterns did you use? Drop a comment!

Discussion Topics:

Async patterns for LLM integrations
Local vs cloud LLM trade-offs
Resume optimization strategies
Full-stack Java + React workflows

Secure Python Litestar Site With OpenID/OIDC Using Okta Hosted Login

Pete Letkeman — Fri, 16 Feb 2024 22:09:18 +0000

Here is a tutorial on how to setup OKTA as a OpenID/OIDC security provider for a site programmed in Python 3.11.x using Litestar.
This is done with 'Authorization Code flow'

About the Authorization Code grant

The Authorization Code flow is the recommended method for controlling access to web applications capable of securely storing secrets, see https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/

OKTA Setup

Step 1

After you have created your OKTA account open `Applications` => `Applications` as seen on the right.

Step 2

Click Create App Integration

Step 3

Choose OIDC - Open Connect with a description of
'Token-based OAuth 2.0 authentication for Single Sign-On (SSO) through API endpoints. Recommended if you intend to build a custom app integration with the Okta Sign-In Widget.'

And then choose Web Application with a description of
'Server-side applications where authentication and tokens are handled on the server (for example, Go, Java, ASP.Net, Node.js, PHP)'

And Click Next

Step 4

Checked the following (may not matter):

Client Credentials
Refresh Token
Implicit (hybrid)

Step 5

Ensure that both Sign-in redirect URIs and Sign-out redirect URIs (Optional) have the correct values. By default Litestar brings up the web site on port 8000.

Step 6

In Assignments select Allow everyone in your organization to access.
In Enable immediate access (Recommended) select Enable immediate access with *Federation Broker Model*
Click Save

Step 7

Create a text file named '.env' and from the General tab, copy both Client ID and Client Secret to the file to have something like the following:

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
OKTA_DOMAIN=dev-123456789.okta.com
REDIRECT_URL=http://localhost:8000/authorization-code/callback
OKTA_PROMPT=consent

And provide the you value for OKTA_DOMAIN.

You do not to supply a value for OKTA_PROMPT or even include it if you choose not to. For more details about regarding this parameter see https://developer.okta.com/docs/reference/api/oidc/#parameter-details.
Using OKTA_PROMPT is very helpful when testing multiple user accounts.

Python Code

Github.com repository found here https://github.com/pbaletkeman/litestarOpenID

Copy the .env file from the previous step to the root directory of your Python project.

For the most part the code is well documented, however here are some notes:

It uses Mako templates, https://www.makotemplates.org/
/profile is not secured, and is used to show you JWT Bearer Token which is needed to access /read-items and other secure routes, this is set in the callback method
More user properties are found in the user_response object located in the callback method

Additionality PKCE

You can use Authorization Code Grant with Proof Key for Code Exchange (PKCE) which you can read about here:
https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/#about-the-authorization-code-grant-with-pkce.

To enforce PKCE you will have to select 'Require PKCE as additional verification' as seen in the image below.

You can still use PKCE without requiring it.

Here is the Python code for this,
https://github.com/pbaletkeman/okta-litestar-oidc-pkce
Which is a lot like the none PKCE code.
Note that the following have been added/changed:

lines: 181, 182, 192, 193

'code_challenge': code_challenge,
'code_challenge_method': 'S256',

line: 231
query_params = {'grant_type': 'authorization_code', 'code': code,

line: 185, 197
And the response_mode has been changed from 'query' to 'form_post' which tells OKTA to send the data as a form post instead of using the query string. Query string is still valid and can be used if you choose to.

Secure Litestar APIs with OKTA

Pete Letkeman — Sat, 10 Feb 2024 20:08:09 +0000

I borrowed a lot from https://developer.okta.com/blog/2020/12/17/build-and-secure-an-api-in-python-with-fastapi thanks to Karl Hughes for this article.

Litestar framework for Python 3.x creating APIs.
For more information about Litestar visit https://litestar.dev/

OKTA Setup

Step 1

After creating a developer account with okta click 'Applications' then 'Create App Integration' as shown in the image

Step 2

Choose 'API Services' with a description of
'Interact with Okta APIs using the scoped OAuth 2.0 access tokens for machine-to-machine authentication.'

Step 3

Give the integration a name
Result Screen

Step 4

In the directory for the Python project create a file named .env with the following:

OKTA_CLIENT_ID=Value From The Previous Step OKTA_CLIENT_SECRET=Value From The Previous Step OKTA_ISSUER="{oktaDomain}/oauth2/default" OKTA_TOKEN="{oktaDomain}/oauth2/default/v1/token" OKTA_INTROSPECTION="{oktaDomain}/oauth2/default/v1/introspect" OKTA_AUDIENCE="api://default" OKTA_SCOPE="items"

Step 5

Now go to 'Security' -> 'API' shown below:

Note that values for Audience and Issuer URI are in .env file.

Step 6

Click on the edit icon you should see something like this:

Step 7

Try the 'Metadata URI' in a new tab in you web browser to see something like:

Step 8

Click 'Scopes' -> 'Add Scope'

Step 9

Add a scope such as what is shown below:

Step 10

Complete the .env file with the correct information including replacing {oktaDomain} with your okta domain and having the correct value for OKTA_SCOPE="items", if you changed yours that is and note that OKTA_SCOPE is important for remote validation.

Python Code

You can find the final code for this here https://github.com/pbaletkeman/litestarOKTA.

Large segments of this code came from https://docs.litestar.dev/latest/usage/security/jwt.html.
To learn more about Litestar security go here https://docs.litestar.dev/latest/usage/security/index.html

Download the files to your local system and copy them to your Python project directory.

Step 11

Install the required Python libraries using

pip install -r requirements.txt

Note, that this includes all of litestar[full] which may be more than you need.

Step 12

Libraries of note:

base64 is used to encode your client id and client secret
httpx is used to connect to the OKTA server and return the JWT token
okta_jwt.jwt is used to validate the JWT token locally, which is quicker, but less secure than JWT token validation on the OKTA server
starlette.config is used to import the .env file into your application, you may want to use python-dotenv instead

Step 13

In this sample project we only ever will have one user/account which means that we can do this

API_USER_DB: dict[str, OAuthSchema] = {}

but if you have more than one account you should rethink how your database of users is stored.

Step 14

This project includes a method for local JWT token validation, but it is not used, the remote JWT token validate is used instead.
Remote validation is more secure, takes longer and increases system resource usage as this makes a call to the Introspection endpoint.
The local validation method is def validate(token: str) -> bool: and the remote validation method is def validate_remote(token: str) -> bool:

Notes

Note 1

When running this project you should have the following endpoints:

/login
- uses Authorization header to login
/form-login
- uses data from HTML Form to login
/json-login
- uses data from JSON body to login

as shown below:

Each endpoint has it's purpose and it's up to you to choose the appropriate one.

Note 2

In json_login_handler and form_login_handler there is some funky magic happening here:

auth_header = 'Basic ' + str(base64.b64encode((data.client_id + ':' + data.client_secret).encode('ascii')))[2:-1]

To get the token we must send a authorization header of 'basic' a base 64 encoded version of the username:password. However Python prepends the letter "b" and then surrounds the value with a single quote which is why we are using [2:-1]

Forem: Pete Letkeman

AI-Powered Resume Generator: Architecture & Implementation

Building an AI-Powered Resume Generator: Architecture & Implementation

Overview

Architecture Overview

Key Components & Design Decisions

1. REST API Layer (Spring Boot)

2. Async Background Processing

3. LLM Integration (OpenAI-Compatible API)

Frontend Architecture (React + TypeScript)

Core Hook: useApi

File Upload & Polling Pattern

Data Model: Optimize DTO

Key Implementation Challenges & Solutions

Challenge 1: LLM Response Time

Challenge 2: File Format Conversion

Challenge 3: Local vs Cloud LLM

Challenge 4: Test Isolation

Deployment Considerations

Local Development

Cloud Deployment

Testing Strategy

Performance & Scalability Notes

⚠️ Important Considerations

LLM Hallucination Risk

Processing Time

Code Quality Standards

What's Next?

Lessons Learned

Get Started

Credits

Secure Python Litestar Site With OpenID/OIDC Using Okta Hosted Login

About the Authorization Code grant

OKTA Setup

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

Python Code

Additionality PKCE

Secure Litestar APIs with OKTA

OKTA Setup

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

Step 8

Step 9

Step 10

Python Code

Step 11

Step 12

Step 13

Step 14

Notes

Note 1

Note 2

Core Hook: `useApi`