🔍 Web Application Debugging Case Study: Authentication & Onboarding Failures

📌 Overview

This case study documents the end-to-end debugging of a multi-service web application where authentication and onboarding flows were failing due to misconfigurations, session issues, and service communication breakdowns.

The investigation involved analyzing logs, tracing API flows, and resolving issues across frontend (SvelteKit), backend services, and OAuth integration.

---

🚨 Problem Statement

The application failed during critical user flows:

• ❌ Google OAuth login returned errors
• ❌ Backend was unreachable from UI
• ❌ Session cookies were not persisted
• ❌ Onboarding page resulted in 500 errors

---

🧪 Investigation Approach

The debugging process followed a structured approach:

1. Reproduced errors locally
2. Inspected logs and API responses
3. Validated service connectivity
4. Analyzed environment configurations
5. Traced authentication flow
6. Tested fixes incrementally

---

🧩 Key Issues & Root Causes

1. Backend Connectivity Failure

• UI proxy pointed to wrong port
• Execution service running on different port

2. OAuth Misconfiguration

• Mismatch in environment variable names
• Missing PUBLIC_URL for redirect URI

3. Session Handling Failure

• Cookies not forwarded through proxy
• Browser not storing authentication session

4. Onboarding 500 Error

• Session structure mismatch
• Backend APIs failing silently
• Weak error handling

---

🛠️ Fixes Implemented

• Corrected service port configurations
• Standardized environment variables
• Fixed OAuth redirect handling
• Implemented cookie forwarding in proxy
• Added fallback logic for session parsing
• Improved API error handling

---

📊 Result

• ✅ Google OAuth login works
• ✅ Session persistence fixed
• ✅ Onboarding flow loads correctly
• ✅ System stable for core flows

---

🧠 Skills Demonstrated

• Debugging distributed systems
• API & proxy troubleshooting
• Authentication flow analysis
• Session & cookie handling
• Root cause analysis
• AI-assisted debugging workflow

---

⚙️ Tech Stack

• SvelteKit (Frontend)
• Node.js / Fastify (Backend)
• PostgreSQL
• Docker
• OAuth (Google)
• BetterAuth

---

📂 Detailed Debug Logs

See debug.md for step-by-step debugging process including commands, errors, and fixes.

---

📌 Key Takeaways

• Misconfigured environment variables can break entire auth flows
• Cookie forwarding is critical in proxy architectures
• Small inconsistencies in microservices can cause cascading failures
• Structured debugging is essential in multi-service systems

---

⚠️ Notes

Some features (chat, office integrations) remain incomplete due to missing external API configurations.

---

✅ Status

Partially resolved – core authentication and onboarding working