Building EquiDex ~ an AI-powered platform designed to audit and detect bias in hiring algorithms was an ambitious undertaking. The goal was to process massive datasets, run them through Google’s Gemini models, and generate legally formatted compliance reports in real-time.
While the core logic was sound on local machine, deploying a full-stack, AI-integrated application to the cloud introduced an entirely new class of engineering challenges.
EquiDex in action 👇
https://youtu.be/hNCHpyAO-ZQ?si=miFw9zgBBuuvYWgu
Here is a deep dive into the (a.)architecture, the (b.)roadblocks, and the ultimate (c.)deployment playbook I developed while bringing EquiDex to life.
(A) The Architecture and Arsenal (Tools & Technologies):-
To handle heavy data processing while ensuring a seamless user experience, I decoupled the frontend and backend, selecting specialized tools for each layer of the stack.
FastAPI (Backend Framework): Chosen for its speed and native asynchronous support. Processing 10,000-row datasets and waiting for AI API responses requires non-blocking architecture, and FastAPI handled this flawlessly.
Google Cloud Run (Serverless Compute): I containerized the backend using Docker to ensure environment consistency. Cloud Run was selected because it scales to zero (cost-effective) and spins up instantly when a request hits, making it perfect for a stateless API.
Firebase Hosting (Frontend Delivery): The UI needed to be fast and globally cached. Firebase Hosting provided a blazing-fast CDN for the static assets and configuration files, securely calling the Cloud Run backend.
SQLite (Database): Used as an ephemeral, lightweight data store. It allowed the system to rapidly cache candidate audits in memory (/tmp/ directory) for immediate AI processing without the latency of an external relational database.
Google Gemini API (2.5 Flash & Pro): The brain of the operation. I used Gemini to ingest the statistical outputs from the database and interpret hidden discrimination patterns, utilizing its massive context window and high token limits.
Faker & Pandas (Data Synthesis): To prove the platform could handle enterprise scale, I wrote a Python script utilizing Faker to dynamically generate 10,000 heavily biased candidate profiles, pushing the AI analysis to its limits.
(B) Into the Trenches (Challenges & Triumphs):-
The transition from local development to a serverless container environment is rarely smooth. Here are the critical bottlenecks I encountered and how I tried resolving them.
- The Dependency Blindspot and Docker Contexts:- The Problem: The initial cloud deployments repeatedly crashed with ModuleNotFoundError for packages like python-dotenv and google-generativeai.
The Solution: The issue wasn’t the code; it was the deployment context. Executing the deploy command from within the backend/ directory caused the Google Cloud build system to upload the scripts but ignore the root requirements.txt and Dockerfile. Moving the deployment execution to the project root ensured the entire monolithic context was zipped and built correctly.
- The .gitignore Trap & Relative Pathing
The Problem: The container booted successfully but instantly threw a FileNotFoundError when trying to read fairprobe.config.yaml.
The Solution: Google Cloud’s CLI natively respects .gitignore rules. Since .yaml files were ignored to protect secrets, they were silently stripped from the deployment package. I temporarily bypassed this, but a deeper issue remained: relative pathing (open(“fairprobe.config.yaml”)) breaks inside Docker containers. I rewrote the file-handling logic using os.path.abspath(file) to dynamically generate bulletproof absolute paths, regardless of the host environment.
- Invisible Characters and Strict Cloud Environments
The Problem: The SQLite database initialization crashed the container with a bizarre near “ “: syntax error despite the raw SQL strings looking flawless in the editor.
The Solution: The Linux-based SQLite engine in the Docker image was strictly rejecting invisible, non-breaking space characters (\xa0) that Windows environments often ignore. I completely sanitized the sqlite.py adapter, reformatted the SQL schema, and implemented strict parameterized queries to prevent both syntax breaks and SQL injection vulnerabilities.
- Serverless Amnesia and Read-Only Filesystems
The Problem: The Settings page threw 500 errors when attempting to save configurations, and the AI reports frequently failed to locate the audit data.
The Solution: Cloud Run containers use a strict read-only filesystem (except for the ephemeral /tmp/ directory, which is wiped the moment the container sleeps). I re-architected the app flow: the frontend config was updated to maintain state in memory rather than forcing disk writes, and I optimized the user flow so data ingestion and AI reporting occurred in one continuous, “warm” container session.
(C.) The Deployment Playbook (Key Takeaways):-
Going through this crucible refined my approach to cloud engineering. For developers preparing to deploy their first full-stack application, here are the absolute best practices:
1.Deployments are About Environment Matching: Code that works locally only works because your laptop has specific global variables, relative paths, and installed modules. Dockerizing forces you to explicitly define every single requirement. Never assume the cloud knows what your local machine knows.
Logs are the Ultimate Ground Truth: A generic “503 Service Unavailable” or frontend “Failed to Fetch” tells you nothing. You must read the raw server tracebacks. Finding the exact failing line of code is 90% of the battle.
Design for Ephemerality (Statelessness): When building for serverless platforms like AWS Lambda or Google Cloud Run, assume the server will be destroyed and rebuilt every five minutes. Never rely on the local hard drive to store permanent data, configurations, or sessions.
Manage Secrets at the Container Level: Never hardcode API keys or database URLs in your configuration files. Always use environment variables and inject them securely via CLI or secret managers during the deployment phase.
Test Scale Locally First: AI APIs have strict governors. Before throwing 10,000 synthesized records at a cloud API, test the data pipeline with 10 records. Respect the TPM (Tokens Per Minute) limits, and build error handling for 429 quota codes into your frontend.
Overall learning outcome — —
Deploying EquiDex was a masterclass in debugging, systems architecture, and cloud constraints. It transformed a conceptual prototype into a robust, scalable tool. As a developer, the greatest lesson wasn’t just learning how to write the code, but learning how to teach the cloud to execute it.