From Requirement to Architecture: How I Break Down a Real Product

In my previous posts, I talked heavily about system design philosophy—why the "Happy Path" is a lie, and why you should never write code before drawing boundaries.

But philosophy is cheap. Let’s look at how this works in practice.

Today, we are going to break down an actual product from scratch. We will look at thekedaar, a real-world contractor management application I architected, and trace it from raw requirements down to the data models and scaling limits.

---

1. The Users (Who is this for?)

Before picking a database, you must understand the humans using the system. In a construction app, we have two wildly different personas:

1. The Site Manager (Mobile User): Standing in the sun, wearing gloves, with one bar of 3G internet. They need large buttons, offline capabilities, and speed.
2. The Contractor / Admin (Desktop User): Sitting in an office with fast Wi-Fi. They need complex data grids, reporting dashboards, and architectural file exports.

💡 Design Decision: The mobile app must be built "Offline-First". The web dashboard can be a standard SPA (Single Page Application).

---

2. The Domains (Drawing the Boundaries)

If you throw everything into one massive utils folder, your project will become unmaintainable in six months. I break the system into Bounded Contexts:

• [ ] Identity & Access: Authentication, role-based access (Admin vs. Site Worker).
• [ ] Project Management: Sites, floor plans, and spatial modeling files.
• [ ] Labor & Attendance: Daily check-ins, wages, and shift tracking.
• [ ] Inventory & Materials: Tracking cement, steel, and daily consumption.

Each of these domains operates independently. Attendance doesn't need to know the price of steel.

---

3. The Data Model (The Foundation)

Here is a simplified look at how I structure the core relational tables. Notice how we keep the tables narrow and reference IDs rather than duplicating data.

-- Projects Table
CREATE TABLE projects (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  status VARCHAR(50) DEFAULT 'ACTIVE',
  created_at TIMESTAMP
);

-- Daily Attendance (High Write Volume)
CREATE TABLE attendance_logs (
  id UUID PRIMARY KEY,
  project_id UUID REFERENCES projects(id),
  worker_id UUID,
  check_in_time TIMESTAMP,
  gps_location POINT,
  sync_status VARCHAR(20) -- Tracks if synced from offline mobile
);

---

4. The APIs & Data Flow

For the mobile app to work offline, our APIs cannot just be simple POST requests. We need a synchronization engine.

The Sync Endpoint: Instead of sending attendance logs one by one, the mobile app batches them into a single payload when it detects a stable connection.

POST /api/v1/sync/attendance

{
  "batch_id": "req-987",
  "logs": [
    { "worker_id": "w-1", "time": "08:00", "status": "PRESENT" },
    { "worker_id": "w-2", "time": "08:05", "status": "PRESENT" }
  ]
}

---

5. Frontend Boundaries & Backend Services

I am a pragmatist. I don't start with 15 Kubernetes microservices for a V1 product.

• Backend: A Modular Monolith in Node.js. It runs as a single server, but the code is strictly separated by the domains we defined in Step 2.
• Storage: PostgreSQL for relational data (users, projects, logs). AWS S3 for heavy BLOB storage (architectural floor plans, spatial exports for Blender/Revit, site photos).
• Frontend: React Native for the Site Managers (leveraging SQLite for local offline storage) and React.js for the Contractor web dashboard.

---

6. Failure Cases (What breaks?)

Architecture is about managing tradeoffs. Here is what I plan for before it happens:

• Conflict Resolution: What if an Admin deletes a worker on the web dashboard, but a Site Manager checks that worker in offline on their phone?
  • Solution: Soft-deletes on the database. The system accepts the check-in, flags it as "Orphaned", and alerts the Admin to resolve it manually.
• Heavy File Uploads: Uploading a 50MB AutoCAD file via the backend will crash the server.
  • Solution: The backend generates an S3 Pre-signed URL. The client uploads the heavy file directly to AWS, bypassing our Node.js server entirely.

---

7. Scaling Considerations

When thekedaar grows from 10 construction sites to 1,000, where will the bottlenecks be?

1. Read-Heavy Dashboards: Admins will load massive attendance reports. We will need to introduce a Read-Replica database so heavy analytical queries don't slow down the mobile app's daily writes.
2. Spatial Data Processing: If we start rendering heavy floor plans in the browser, we will move the parsing logic to an asynchronous background queue (like Redis + BullMQ) so the main API never blocks.

---

The Takeaway

System design is not about drawing perfect boxes on a whiteboard. It is about understanding the human sitting at the end of the screen, mapping out how the data flows to them, and protecting the system from inevitable chaos.

When you build with constraints in mind, the code practically writes itself.

---

For more deep dives into full-stack architecture, visit jeetlabs.in.