Flux

The org as it runs, not as it is drawn.

Comment

Inspiration

Onboarding is still treated like a document problem. A new hire gets a wiki, a few setup links, maybe a PDF, and a manager saying "just ask around." But the real operating system of a team is not in the org chart. It lives in the work: who reviews which code, what is on fire this week, who is unavailable, which topics are sensitive, and which first task is safe to take.

Flux came from seeing that gap from both sides: as someone who has joined teams, and as a hiring manager responsible for helping others ramp. The official onboarding path is usually static. The company is not. The org is always in flux, and a new hire is in flux too.

What It Does

Flux gives every new hire the real team map on day one: what is moving, who owns what, what to avoid, and the first GitLab issue they can safely take.

An HR or team lead generates a Flux onboarding link. The new hire opens it and gets a four-part brief:

  • Right Now: current fires, blockers, and sensitive areas.
  • Your People Map: who actually owns systems, based on GitLab review and issue activity.
  • Week 1 Moves: safe first issues and modules.
  • Landmines: unwritten rules from the team guide.

The new hire can ask follow-up questions like "Who owns auth?", "How do I ship fast?", or "What should I avoid saying in standup?", etc. Flux answers with source grounding from GitLab activity and the team/company guides maintained in Notion.

Flux also moves beyond chat. When the new hire asks to take issue #412, Flux proposes the assignment, waits for explicit confirmation, and then writes the assignment back to GitLab through the GitLab MCP server.

How I Built It

Flux is deployed as a web app on Google Cloud Run.

  • Frontend: React, TypeScript, and Vite.
  • Backend: FastAPI.
  • Agent orchestration: Google ADK LlmAgent and Runner, used as the code-first Google Agent Builder / Agent Platform path.
  • Model: Gemini 2.0 Flash primary, with Gemini 2.5 Flash fallback for Vertex availability.
  • Partner MCP: official GitLab CLI MCP server through glab mcp serve.
  • Team context: Notion API plus deterministic fallback data for demo reliability.
  • Secrets: Google Secret Manager.

The backend reads GitLab issue activity through MCP, reads the Notion team guide, dynamically builds onboarding context, and uses Gemini through ADK to generate the brief and grounded answers. Confirmed actions call GitLab MCP write tools only after the user clicks confirm.

Challenges

The hardest product challenge was keeping the demo clear to restarts for the for the judges. A judge should be able to leave setup fields blank and still see the full value of Flux, so the deployed service supports server-side demo configuration and deterministic fallback data. At the same time, live mode still uses Cloud Run, Gemini, Google ADK, Notion, and GitLab MCP.

The hardest technical challenge was choosing an architecture that solved today’s problem without boxing me in tomorrow. I needed something focused enough for this project, but scalable enough to support multiple sources of company truth as the product evolves.

What I Learned

First: I'm back. I can code again.

This project reminded me how much the new AI development stack changes what one person can build quickly. I started as an engineer, moved into customer-facing technical roles, and Flux was a way to come back to building with a real problem I care about.

As I talked to peers and HR, they confirmed the core insight: the biggest onboarding gap is not lack of documentation. It is lack of living ground truth.

I also realized that my own recent company stack, Notion, Slack, GitHub, and Linear, is not necessarily where Flux has the best chance of success. The product needs to expand across the tools different companies actually use, including GitLab for this hackathon track.

Finally, I learned that a strong agent demo needs to show more than answers. The memorable moment is when Flux turns guidance into a real-world action: assigning the first GitLab issue.

Why It Matters

Every growing company pays the onboarding tax. Slow ramp time costs salary, manager attention, and team momentum. Flux turns scattered work signals into a day-one map that helps a new hire avoid the wrong work, find the right people, and make a real contribution faster.

Built With

  • docker
  • fastapi
  • gemini-2.0-flash
  • gemini-2.5-flash
  • gitlab-cli
  • gitlab-mcp
  • google-adk
  • google-cloud-run
  • google-secret-manager
  • notion-api
  • pytest
  • python
  • react
  • typescript
  • vertex-ai
  • vite
Share this project:

Updates