BuilderLab began with a simple observation: the current way of learning does not reflect the actual dynamics once hired. Solo projects or tutorials rarely reproduce the conditions of team delivery. BuilderLab is therefore an attempt to close the gap between learning and working stages.
BuilderLab treats this missing team experience as a product problem rather than another isolated exercise. It lets learners propose projects, find collaborators, coordinate work, maintain a Build Log and expose enough of the process for another person to understand how the result was reached — not only what the final interface looks like.
01The collaboration gap is a testable engineering problem
Students can practise SQL, Git, Linux, cloud deployment or a programming language alone. The difficult parts of professional engineering are often elsewhere: negotiating scope, dividing responsibility, handling disagreement, documenting decisions, recovering from blockers and maintaining a shared system after its first release.
Knowing a tool is not the same as working in a team
A solo tutorial can teach syntax and APIs. It cannot fully reproduce ownership, handovers, access control or the consequences of another person's change.
The final screenshot hides most of the work
A project page can preserve milestones, updates, blockers, decisions, contributors and feedback so that the path to the result remains inspectable.
Once we are employed as engineers, we work with other people every day. BuilderLab turns that ordinary fact into the organising constraint of the product.
Identify a recurring learning or collaboration problem.
Translate the problem into roles, states and transitions.
Build the smallest coherent flow and expose it to real use.
Record failures, tighten boundaries and define the next experiment.
02Three product layers follow one project from idea to review
The product is divided into three connected layers. I use the separation to keep distinct problems visible rather than hiding them behind one broad idea of “collaboration”.
Profiles, project ideas, discovery, join requests, team membership, following and public project pages.
LiveTasks, milestones, team chat and Build Log updates inside the project workspace.
Live / evolvingA completed-project index is live; structured peer reviews and their scoring method remain planned.
Partly live / plannedThe intended lifecycle is more than project matching. A request can become membership; membership opens a workspace; selected task transitions can create public Build Log entries; project completion can lead to collaborator ratings; and a completed project can remain available as evidence. Each step requires an explicit state transition rather than only a new screen.
03The application separates public discovery from authenticated work
The current repository uses Next.js App Router with TypeScript. Route groups separate the public surface from the application workspace without changing the public URLs. Server Components obtain initial page data; Client Components handle forms, filters, modals, chat, task changes and optimistic interface updates.
The typical page flow is a Server Component reading rows and identity context before handing the result to a Client Component for interaction. This is visible in the feed and project-detail flows.
fetch projects + current user
search, filters, ownership context
join requests and follow actions
04The data model follows the social and technical life of a project
The most important modelling decision was to avoid treating a project as only a title and description. BuilderLab represents identity, discovery, team formation, execution, completion and feedback as related but different concerns.
A connection is a request, not membership. A follower can inspect restricted project sections but cannot act as a member. A member can leave without disappearing from the historical record. A task can be assigned, blocked or linked to a milestone. A public update is different from a team message. These distinctions make the product idea visible in the schema and give access policies something precise to enforce.
pending to accepted, a PostgreSQL trigger inserts the sender into project_members. The transition is atomic and does not depend on a client successfully performing a second request.05Trust boundaries should survive a direct API call
Authentication is not the same as authorisation. Hiding a button can guide a user, but it cannot protect a database. For the flows below, the interface and PostgreSQL Row Level Security share responsibility: the interface presents the valid actions, while database policies reject operations outside the authenticated user's role.
Q1Who may change a task?
The project owner can create, modify or delete any task. The owner may delegate the HiveOS Manager role to one active member at a time, giving that person the same task-management rights. A regular member may update the status of a task assigned to them. The policy checks the owner, manager and assignee identities at database level.
Current limitation: the database controls who may update an assigned task, but the detailed set of allowed status transitions is still largely guided by the interface. A stricter transition policy would reduce that remaining trust in client behaviour.
Q2How does an accepted request become membership?
A request begins as a row in connections. After the owner accepts it, a PostgreSQL trigger creates the active project_members row with conflict protection. This keeps acceptance and membership consistent even if a caller bypasses the interface.
Q3What happens when a member leaves?
Leaving voluntarily and removal by the owner both require a reason of 10–300 characters. The membership row changes to left instead of being deleted, the rating requirement is cleared, access to team-only functions is removed, and remaining assigned tasks become unassigned. The reason is not shown to the wider team.
The current specification also exposes a cleanup case: if the departing member was HiveOS Manager, the manager flag can remain stored even though the member no longer has access. Automating that cleanup is a reasonable next database change.
Q4Which project sections are public?
Milestones, Build Log, Team Chat and Team members each have an independent owner-controlled toggle and are public by default. When restricted, they remain visible to the owner, active members and followers. Followers therefore form an intermediate trust tier: they can inspect more context but cannot post updates, chat or use HiveOS.
This means “private” currently means restricted to a defined project audience, not visible only to the active team. The wording and interface need to keep that distinction clear.
Q5How are notifications sent without exposing email addresses?
Email and in-app notifications are created through server-side route handlers using the Supabase service-role key, which is never sent to the browser. The route reads the recipient's email on the server, sends the email through Resend and creates an in-app notification. Notification rows are readable only by their intended recipient through RLS.
Keeping the key server-side is necessary, but not sufficient. These routes should continue to gain explicit caller and workflow verification, input validation, rate limiting and operational logging.
Q6How does documentation remain aligned with the database?
At present, alignment depends on discipline rather than an automated proof. I apply each migration to a development Supabase project, update the database documentation immediately, record the product change in the changelog, and commit migration, documentation and application code together.
This is the weakest boundary in the current process because nothing automatically demonstrates that the documentation matches the live schema. Schema introspection and a documentation diff are natural next experiments.
06A live product turns lessons into changes in method
The codebase has grown while I have been learning. That is visible in useful features, but also in files that have become too large, migration history that does not yet provide a complete reproducible path, five-second polling in team chat, and an earlier quickstart that refers to SQL setup files no longer present in the supplied archive.
Testing is the clearest example of a changed method. I did not begin BuilderLab with an automated testing strategy. That was an oversight. During an MLOps class, the advice to introduce tests early rather than retrofit them after the system becomes difficult to change made the cost of that decision clearer. I have since written a testing strategy on the development branch. It is a start, not yet a complete automated suite or a continuous-integration gate.
I am taking a similar approach to infrastructure. I could patch the old SQL quickstart immediately, but the intended direction is a declarative environment built with Terraform. I would rather establish that process after covering the relevant concepts and then replace the obsolete setup path once, instead of refreshing instructions that I already expect to supersede.
07What the beta demonstrates—and what I would test next
Current evidence
- Public and authenticated routes are separated without changing the external URL structure.
- Server, browser and service-role Supabase clients represent different trust boundaries.
- The domain model distinguishes requests, followers, members, owners, managers, tasks, milestones, updates, chat and ratings.
- HiveOS turns selected task events into Build Log evidence without publishing every internal action.
- Database triggers protect important transitions such as profile creation and accepted-request membership.
- The product is deployed as a live beta with public documentation and source code.
Known constraints
- The migration history should become the reproducible source of truth for the current schema.
- Several interactive components need decomposition before they become harder to test and maintain.
- Team chat polling should be replaced or made incremental as usage grows.
- The testing strategy must become executable tests and an automated gate.
- The quickstart should be replaced by a declarative provisioning path rather than patched indefinitely.
- Documentation-to-schema alignment still needs an automated check.
Exercise owner, manager, assignee, follower and unauthorised API calls against RLS policies.
Verify accepted requests, departures, task unassignment and manager cleanup as database-level state transitions.
Check caller identity, expected workflow state, recipient isolation and failure behaviour before sending email.
Introspect the development schema and compare it with migrations and generated documentation.
Use Terraform to make the development setup repeatable and retire the obsolete SQL quickstart.
Compare Realtime or incremental polling with the current five-second polling approach under realistic activity.
None of these steps is valuable merely because it uses another tool. Each should answer a specific question: does the policy reject the wrong actor, can the environment be reproduced, does the documentation detect drift, or does a new messaging mechanism reduce reads without weakening delivery?
08Open evidence
BuilderLab remains a live beta. The links below expose the product, its user-facing documentation and the source repository so that the claims in this article can be inspected rather than accepted on description alone.