DEV Community: Abhishek.M. Shivanagoudar

"My Mergetober story: building a BambooHR connector for cognee"

Abhishek.M. Shivanagoudar — Wed, 07 Oct 2026 22:27:58 +0000

This Mergetober I wanted to do more than fix a typo. I wanted to build something real, get it reviewed, and actually understand every line of it. I ended up building a BambooHR connector for cognee, and this post is the story of how it went, mistakes included.

Finding the issue

cognee is an open source project that turns your data into a knowledge graph AI agents can search, basically long-term memory for agents. It uses "connectors" to pull data in from tools like Notion, Gmail and Google Drive.

While browsing the issues I found #4795: add a connector for BambooHR, an HR platform. The idea was simple: if your company's employee directory and handbooks are in BambooHR, your AI agent should be able to answer "who works in Sales?" or "how many days of leave do we get?"

The issue suggested copying the existing Notion connector. Before commenting, I read through BambooHR's API docs and noticed something important: BambooHR has a change feed, an endpoint that tells you exactly which employees were added, updated or deleted since a given time.

The Notion connector re-downloads everything every run and replaces the old data, because Notion has no such feed. If I copied that approach but only fetched changes, every employee who didn't change would get wiped from memory. So in my comment I proposed using the change feed with a merge strategy instead, like the Gmail and Google Drive connectors do. I also asked what should happen to employees who leave the company.

That comment got me assigned. 🎉

Setting up (and immediately messing up)

My first hour was mostly Git mistakes:

I forked cognee instead of cognee-community. The issue lives in the main repo, but connectors actually go in the community repo.
I ran git init in the parent folder instead of inside the cloned repo.

Not my proudest moment, but it's the kind of thing you only do once.

Making a BambooHR trial account

I didn't have access to a real company's BambooHR (and wouldn't want to test on one anyway), so I signed up for a free BambooHR trial. It comes preloaded with around 118 fake employees and about 20 company files like handbooks and policies, which turned out to be perfect for testing.

I spent a while just calling the API by hand to see what it actually returns. That's where I learned two things that shaped the whole design:

The first sync doesn't need a separate endpoint. If you ask the change feed for everything since 1970-01-01, every employee comes back as "Inserted". One code path handles both the first sync and every sync after it.
BambooHR returns only the employee id unless you ask for specific fields. That meant I could make the connector private by default: it only ever requests safe fields like name, job title and department. Salary, SSN, date of birth and home address are never even fetched.

Building it

The connector syncs two things: the employee directory and company files (PDF, TXT, MD, CSV).

For employees, it uses the change feed and stores BambooHR's own timestamp as a cursor for the next run. That cursor is only saved once the whole run succeeds, so a crash halfway doesn't skip anything. Deleted employees are removed, and terminated employees (which BambooHR marks as Inactive) are forgotten by default too.

Files were trickier because BambooHR has no change feed for them. So each run lists all files, compares them with the previous run to spot deletions, and lets cognee skip files whose content hasn't changed.

Testing with Ollama on Windows

I didn't want to pay for API calls while experimenting, so I ran everything locally with Ollama, using llama3.1:8b as the LLM and nomic-embed-text for embeddings. This is where most of my debugging time went.

Ollama models "downloaded" but didn't exist. ollama pull said success, yet ollama list was empty. It turned out Ollama 0.40.0 stores model manifests as symlinks, and Windows 11 refused to follow them. Replacing the two symlinks with real copies of the files fixed it.

Windows' 260-character path limit. cognee's vector store creates deeply nested folders, and my long project path pushed it over the limit. Moving the data to a short folder fixed it.

The model returned the schema instead of the data. cognee asks the LLM for JSON in a fixed shape, and the small 8B model sometimes replied with the description of the shape instead. Adding this to .env solved it:

LLM_INSTRUCTOR_MODE="json_schema_mode"

Once it all worked, I loaded a few mock employees and a leave policy and asked:

"Who works in the Sales department?" → it named the right person.
"How many days of paid leave do employees get?" → "every employee gets 24 days of paid leave per year."

Then I deleted that Sales employee upstream, synced again, and watched cognee's document count drop from 4 to 3. Seeing it forget someone was honestly the most satisfying moment of the project.

Testing against the real trial

Next I ran the connector against my BambooHR trial four times, making changes in between:

Run	Employees fetched	What happened	Stored
1 (first sync)	108	Deleted and inactive sample employees skipped	88
2	20	Picked up my edits	88
3	5	One deleted, one terminated	87
4	2	Caught an employee I terminated while run 3 was still running	86

Run 4 was a nice confirmation that saving the cursor only at the end really works: nothing slipped through.

The trial also surprised me. One of the sample files was a Benefits CSV with per-employee data in it. My field allowlist protects the employee directory, but it can't protect against a file like that. So I added a file_categories option to let you choose exactly which file folders get synced. Another sample PDF turned out to be genuinely corrupt, so I made sure broken files are skipped with a warning instead of crashing the run.

Alongside the live tests I wrote 33 unit tests with a mocked API, so reviewers can run them without a BambooHR account.

Opening the PR

I opened the PR… and CI failed immediately. The repo requires a DCO sign-off on every commit, which I'd never heard of. The fix:

git rebase --signoff upstream/main
git push --force-with-lease

How to use it

If your team uses BambooHR, here's all it takes:

cd packages/connector/bamboohr && uv sync
export BAMBOOHR_COMPANY_DOMAIN=acme   # from https://acme.bamboohr.com
export BAMBOOHR_API_KEY=...           # BambooHR → your name → API Keys

import asyncio
import cognee
from cognee_community_connector_bamboohr import bamboohr_source

async def main():
    await cognee.remember(
        bamboohr_source(),
        dataset_name="bamboohr",
        primary_key="id",
        write_disposition="merge",  # important: cognee's default is replace
    )

    answer = await cognee.search(
        query_text="Who works in the Sales department?",
        query_type=cognee.SearchType.GRAPH_COMPLETION,
        datasets=["bamboohr"],
    )
    print(answer)

asyncio.run(main())

Run remember again anytime and only the changes are synced. You can also pass include_inactive=True to keep former employees, or file_categories=["Company Files"] to limit which files are synced.

What I learned

Read the API before writing code. One look at BambooHR's change feed changed the whole design, and it's what got me the issue.
A trial account beats mocks. The broken PDF, the Benefits CSV and the inclusive timestamps only showed up with real-ish data.
Local LLMs are great for learning, as long as you're ready to debug your OS along the way.
Privacy is easier to design in than to bolt on. Never requesting sensitive fields is safer than filtering them out later.

Thanks to the cognee maintainers for the guidance on the issue, and to the WeMakeDevs community for Mergetober pushing me to ship something real.

Links

Mergetober #WeMakeDevs #OpenSource

Building CampusEvac | How We Won Best UI at First Commit

Abhishek.M. Shivanagoudar — Thu, 01 Oct 2026 10:07:30 +0000

Two perspectives, one shared emergency, and the engineering behind a real-time evacuation simulation.

A fire evacuation is not just a problem of finding the nearest exit. It is also a problem of understanding what is happening across a building, communicating information, and coordinating people who see the same emergency from different perspectives.

We wanted to explore that problem through a browser-based simulation.

CampusEvac was our attempt to turn an evacuation drill into an interactive, real-time experience. One participant navigates the building as an evacuee, while another observes the scenario as a warden. Both interact with the same simulation, but neither sees it in quite the same way.

We built CampusEvac during First Commit, a WeMakeDevs hackathon, and our project was recognised in the Best UI track.

This is a look at the problem we chose, the architecture behind the application, the design decisions that shaped the experience, and what building a real-time product taught us.

Why Build an Evacuation Simulator?

Emergency preparedness involves more than documenting procedures. People need opportunities to understand their environment, practice decisions, and become familiar with how an evacuation might unfold.

Physical drills serve an important purpose, but organising them requires coordination and a suitable environment. We wanted to explore how a browser-based simulation could provide another way to practise and understand evacuation scenarios.

That led us to a question:

What if two people could participate in the same evacuation drill from completely different roles, directly in their browsers?

The answer became CampusEvac.

Instead of creating a static building map or a conventional monitoring dashboard, we designed a two-player experience with a shared environment and role-specific interfaces.

The project had three central requirements:

A navigable building environment for the evacuee.
An overhead monitoring interface for the warden.
Real-time communication so that both participants could interact with the same evolving simulation.

These requirements shaped both our interface design and our technical architecture.

Two Roles, Two Different Interfaces

One of the most important decisions was to avoid treating the evacuee and warden as two versions of the same user.

They have different responsibilities, different information needs, and different ways of understanding the building.

The evacuee: navigating the situation

The evacuee interacts with the environment from a first-person perspective.

The interface needs to keep the building and navigation experience central, allowing the participant to understand their surroundings and make decisions without unnecessary interface clutter.

The warden: understanding the bigger picture

The warden sees the building from an overhead perspective.

Rather than navigating from ground level, the warden needs to understand the broader scenario and observe what is happening across the environment.

That calls for a different information hierarchy, a different layout, and controls designed around monitoring rather than first-person movement.

Why the distinction matters

A role-based application should not simply change a heading or swap a few buttons when the user changes roles.

The interface should reflect what that person needs to accomplish.

For CampusEvac, we treated the two perspectives as complementary parts of the same experience. The evacuee focuses on navigating the environment; the warden focuses on observing the wider situation.

This principle extends to many other applications, from collaborative tools to logistics dashboards and real-time monitoring systems.

The Real-Time Problem

Two browser windows showing the same building do not automatically create a shared simulation.

When participants interact independently, the application needs a way to communicate changes, manage connections, and keep the experience coherent.

For CampusEvac, we used AWS AppSync Events for real-time communication and Amazon DynamoDB for application state.

At a high level, the architecture consists of three main parts:

Component	Responsibility
Browser application	Provides the evacuee and warden interfaces
AWS AppSync Events	Enables real-time communication between connected participants
Amazon DynamoDB	Stores application state persistently

The distinction between real-time communication and persistent state is important.

A message can communicate that something has changed, but a message and a durable record of application state are not the same thing. A robust implementation needs to define which information is persisted, how updates are propagated, and what happens when a participant disconnects and returns.

These questions become especially relevant in collaborative applications, where the experience depends on multiple clients interacting with shared state.

Our architecture gave us a foundation for combining a browser-based simulation with AWS-managed real-time communication and persistence.

Why UI Was More Than Visual Polish

The Best UI track gave us a reason to look closely at what makes an interface effective in the first place.

It is tempting to equate good UI with gradients, animations, typography, and polished components. Those elements can contribute to the experience, but they do not replace clear interaction design.

CampusEvac has an additional challenge: the interface needs to communicate a situation that changes over time.

The evacuee needs an interface that supports navigation. The warden needs an interface that supports observation. Both need to understand that they are participating in the same simulation.

That makes several design considerations particularly important:

Role clarity. Participants should be able to understand their responsibilities from the interface they are using.

Information hierarchy. The most relevant information should be easy to distinguish from secondary controls and status indicators.

Contextual feedback. Changes in a shared environment need to be communicated clearly enough that participants can understand what has happened.

Functional consistency. The interface should remain understandable while the application is running, not merely in a static screenshot.

The central idea is that UI quality depends on how effectively an interface supports its intended task.

A visually polished interface is useful. A visually polished interface that also communicates the system's behaviour is more useful still.

Building Under Hackathon Constraints

Hackathons require teams to make decisions quickly. There is limited time to explore a problem, choose a stack, implement the main experience, integrate services, test the application, and prepare a demonstration.

For CampusEvac, we concentrated on the core interaction: two roles, two perspectives, and one shared simulation.

We also incorporated AI coding agents into our development workflow.

These tools helped accelerate implementation, but generating code was only one part of the process. The application still needed architectural decisions, integration work, and testing across its different components.

A component can render correctly on its own while the complete application behaves incorrectly when two participants interact simultaneously.

That distinction matters particularly in real-time systems. Testing an individual interface is not a substitute for testing the relationship between connected clients.

Our experience reinforced a useful principle: AI-assisted development can reduce implementation effort, but it does not remove the need to understand the system being built.

The quality of the result still depends on defining the problem clearly, making sound decisions, and verifying that the pieces work together.

What We Would Improve Next

CampusEvac gave us a working foundation, but a simulation of this kind has several areas worth exploring further.

Some possible directions include:

Larger building scenarios: More detailed environments that allow for varied evacuation routes and layouts.
Clearer monitoring interfaces: Better ways to communicate the overall state of a drill without overwhelming the warden with information.
Reconnection handling: More robust behaviour when a participant leaves a session and later returns.
More extensive real-time testing: Testing concurrent interactions, changing connection states, and the consistency of shared information.

These are potential improvements, not claims that every feature is already implemented.

The broader challenge is to make the simulation useful beyond a successful demonstration: predictable behaviour, understandable interfaces, and a system that remains coherent when real users interact with it.

The Result: Best UI at First Commit

CampusEvac was recognised in the Best UI track at WeMakeDevs' First Commit hackathon.

For us, the project brought together several areas of engineering: interface design, browser-based interaction, real-time communication, persistent state, and AI-assisted development.

The recognition was a milestone, but the process was equally valuable. It gave us an opportunity to think about how design decisions affect a product's functionality and how architectural choices influence the experience users ultimately see.

I'm grateful to WeMakeDevs for the opportunity to participate, and to my teammates Afreen and Akshay for building CampusEvac with me.

Try CampusEvac

The best way to understand the project is to explore the two perspectives and see how they fit together.

Live demo: Explore CampusEvac
Demo video: Watch the walkthrough
wemakedevs: showcase

CampusEvac started with a simple idea: make an evacuation drill interactive and shared. Building it taught us how much work goes into connecting the interface, the underlying system, and the experience of the people using it.

That is what made this project worth building.

Built by Abhishek M. Shivanagoudar, Afreen, and Akshay for WeMakeDevs First Commit.