Backend Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The TestGenAI project features two distinct backend architectures for handling repository analysis and test generation. The original implementation uses a dedicated Go backend server. A newer, alternative implementation replaces this with a "client-side backend" that runs entirely in the browser, communicating directly with external APIs. This document outlines the architecture and deployment considerations for both approaches.
The primary backend logic involves cloning a GitHub repository, creating a "code context" from its files, and using that context to generate tests via the Google Gemini API. The deployment model determines where this logic is executed: on a dedicated server or within the user's browser.
Sources: README.md, testgen/CLIENT_BACKEND.md
1. Go Backend (testgen-backend)
This is the traditional server-based architecture where a Go application handles all core logic. The frontend (React) communicates with this backend via a set of REST APIs.
Sources: README.md, testgen-backend/main.go
Architecture
The Go backend acts as an intermediary between the frontend client, the git command-line tool, the local filesystem, and the Google Gemini API.
The diagram below illustrates the Go backend architecture.
API Endpoints
The Go server exposes three main HTTP endpoints on port 3001.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/clone-repo | Clones a public GitHub repository, filters relevant files, generates a context file, and returns metadata. |
POST | /api/generate-tests | Sends the code context and an API key to the Gemini API to generate test cases. |
GET | /api/context/{owner}/{repo} | Retrieves a previously generated context file from the local repos directory. |
Sources: README.md, testgen-backend/main.go:349-351, testgen-backend/main.go:453-455, testgen-backend/main.go:420-422
POST /api/clone-repo
This endpoint orchestrates the analysis of a GitHub repository.
The sequence diagram for a repository clone request.
Sources: testgen-backend/main.go:354-418
POST /api/generate-tests
This endpoint interacts with the Google Gemini API to generate tests.
| Parameter | Type | Description |
|---|---|---|
apiKey | string | The user's Google Gemini API key. |
codeContext | string | The concatenated content of the repository files. |
additionalPrompt | string | (Optional) Extra instructions for the AI. |
Sources: testgen-backend/main.go:73-77, testgen-backend/main.go:463-473
Deployment & Execution
To run the Go backend for local development:
- Navigate to the
testgen-backend/directory. - Install dependencies:
go mod tidy - Run the server:
go run main.go - The server will start on
http://localhost:3001.
The server requires the git command-line tool to be installed and available in the system's PATH. It creates a repos/ directory to temporarily store cloned repositories and generated context files.
Sources: README.md, testgen-backend/main.go:159, testgen-backend/main.go:616-618
2. Client-Side Backend
As an alternative to the Go server, a "client-side backend" was implemented in TypeScript. This approach moves all logic into the browser, eliminating the need for a dedicated server for cloning and test generation. The frontend application communicates directly with the GitHub and Gemini APIs.
Sources: testgen/CLIENT_BACKEND.md, testgen/src/lib/backend.ts
Architecture
The client-side backend is encapsulated within the ClientBackend class. It leverages browser fetch APIs to interact with external services.
The diagram below shows the client-side backend architecture.
Key Logic (ClientBackend Class)
The ClientBackend class in src/lib/backend.ts mirrors the Go backend's functionality.
| Method | Description |
|---|---|
cloneRepository | Parses a GitHub URL and uses the GitHub Contents API to recursively fetch file information and content, bypassing the need for git clone. |
fetchFilesRecursively | A helper that traverses repository directories via the API, respecting file size limits (50KB) and exclusion patterns. |
generatePromptContext | Organizes the fetched file content into a structured string, similar to the Go implementation. |
generateTests | Constructs a prompt and sends it directly to the Gemini API from the browser. |
parseGitHubUrl | Extracts the owner and repository from a GitHub URL string. |
Sources: testgen/src/lib/backend.ts:114-120, testgen/src/lib/backend.ts:223-231, testgen/src/lib/backend.ts:168-173, testgen/src/lib/backend.ts:340-344, testgen/src/lib/backend.ts:480-483
The ApiService class abstracts the backend calls. It was updated to call the ClientBackend methods directly instead of making fetch requests to the Go server, facilitating a seamless migration.
Sources: testgen/src/lib/api.ts:21-23, testgen/CLIENT_BACKEND.md
Deployment & Execution
This model simplifies deployment significantly. Since there is no custom server, the entire application can be deployed as a static site.
- Build the React frontend:
npm run build - Deploy the resulting static files (from the
distfolder) to any static hosting service like Vercel, Netlify, or GitHub Pages.
Considerations:
- CORS: Direct API calls from the browser to the GitHub API are subject to CORS policies and may fail when running on
localhost. - API Keys: The Gemini API key is handled on the client side, which requires careful management to avoid exposure.
- Rate Limiting: The application is subject to the GitHub API's unauthenticated rate limit (60 requests/hour).
Sources: testgen/CLIENT_BACKEND.md, testgen/package.json:7, testgen/src/pages/Dashboard.tsx:125-130
3. Deployment Model Comparison
The choice of backend determines the project's deployment strategy, cost, and maintenance overhead.
| Feature | Go Backend Model | Client-Side Backend Model |
|---|---|---|
| Server Required | Yes, a server capable of running a Go binary. | No, only static file hosting. |
| Dependencies | Go (1.21+), Git CLI | None (relies on browser APIs). |
| Deployment | Deploy Go binary + static frontend files. | Deploy static frontend files only (e.g., to Vercel/Netlify). |
| Performance | Server round-trip for all operations. | No server round-trip; direct calls from browser to APIs. |
| Cost | Server hosting costs. | Static hosting costs (often free for small projects). |
| Security | API keys are managed on the server. | Gemini API key is exposed in the browser. |
| CORS/Rate Limits | Not an issue for server-to-server calls. | Subject to GitHub API CORS and rate limits. |
Sources: testgen/CLIENT_BACKEND.md, README.md
Conclusion
The TestGenAI project offers two backend deployment paths. The Go backend provides a robust, secure way to manage API keys and is not subject to browser-based limitations like CORS, but it requires server hosting and maintenance. The client-side backend dramatically simplifies deployment and reduces cost by offloading all work to the user's browser, making it ideal for quick, serverless deployments, albeit with security and rate-limiting considerations for the client-managed API interactions. The project has migrated to favor the client-side approach for its simplicity and ease of deployment.
Sources: testgen/CLIENT_BACKEND.md