Skrzynka Spółdzielni

#DEV LOG: Entry #01 — From Client Brief to System Design

Date: June 7, 2026 Status: Ideation complete — first build starts next week

#Where This Started

The client came to us with a clear operational pain point: their housing cooperative's maintenance workflow was completely unstructured. Work orders arrived through informal channels — phone calls, messages, word of mouth — and there was no reliable way to track who was responsible for what, what state each job was in, or how long things were actually taking.

Their brief boiled down to this:

"We need a place to register maintenance jobs, assign them to the right people, and let everyone see what's happening — with different levels of access depending on the role."

Simple brief. Genuinely complex to get right.

#What We Designed Together

Over the past week we've been iterating on the brief to turn it into a concrete system design. Here's what we've locked in.

#The three roles

The system is built around three distinct user groups with very different needs:

Getting this access model right up front saves enormous pain later — one codebase, three focused interfaces.

#The job lifecycle

Every work order moves through a defined lifecycle:

1. Registered — logged with: who reported it, date, description, location, responsible person
2. Assigned — a technician routes it to the right maintenance worker
3. Acknowledged — the worker confirms they've read it (visible to others)
4. In progress — worker updates status with a comment as work proceeds
5. Closed — marked as completed, or documented as blocked with a reason

The blocked state matters as much as the completed state. If a job can't be done, the system captures why — that data is as operationally useful as knowing a job is done.

#The cross-platform footprint

Field teams don't sit at desks. From day one the system targets:

• Next.js web app — responsive down to mobile browser
• PWA — offline-capable for spotty connectivity in the field
• Electron desktop shell — for office-based coordinators and managers
• React Native app — native push notifications and SMS fallback (Phase 2)

#Why Human-in-the-Loop from day one

Rather than building AI automation and hoping it's reliable enough to trust, we're using a Human-in-the-Loop (HITL) model for the first phase:

[ Job registered ] ──► [ Normalized ] ──► [ Staging view ] ──► [ Human assigns & approves ] ──► [ Active ]

Nothing moves to active status without a human sign-off. This makes the system 100% reliable from the first day of use, while we gather the real operational data needed to make any future automation actually trustworthy.

#Statistics for management

Managers get a read-only view with the metrics that matter:

• Time from registration to completion per job
• Average completion time across job types
• Number of jobs currently in progress

#What's Next

The ideation phase is done. We have a clear system design, agreed role model, and a cross-platform architecture that won't need to be rebuilt when the load grows.

First MVP build starts Monday or Tuesday next week.

The first working version will cover the core loop: job registration, assignment, status updates, and role-based views — enough for the client to put real work through it from day one.

Next entry: first build in progress, early UI decisions, and any surprises that came up when real code hit real requirements.