TeamShastra — Field Workforce Management SaaS (On Going)

Key engineering decision

Go offline-first with event-driven sync instead of continuous polling.

Most of the people who will actually use TeamShastra are field technicians moving between sites — sometimes with patchy 4G, sometimes with no signal at all. A constantly-polling app would drain their battery, burn data, and still fail when they need it most. So the whole architecture is designed around a local-first store on the device, with a sync queue that pushes changes when the network is available. This one choice shapes everything else — how the Riverpod state is structured, how the FastAPI endpoints are designed, and how conflicts are handled.

---

Architecture summary

System topology and platform shape

• Flutter app (mobile + PWA) — single codebase for Android, iOS, and a PWA fallback for desktop managers. Riverpod for state, repository pattern for data access.
• FastAPI backend — REST APIs, JWT auth, role-based access control (Owner, Manager, Technician), audit logging, validation at the edge.
• PostgreSQL — single source of truth for all business data — companies, teams, customers, work orders, attendance, reports.
• Cloud object storage — for before/after photos, generated PDF reports, and company branding assets.
• Local device storage — for the offline cache and the sync queue that holds pending mutations.

Why this shape

Field workforce apps fail when they assume good connectivity. By keeping a local-first store on the device and treating sync as a background concern, the technician can keep working even when the network is gone. The backend stays simple — plain REST, no realtime pipes, no websockets — which keeps infra costs low and the system easy to reason about.

---

Full writeup — Implementation notes

Where the project stands today

Most of the core is already working end to end:

• Multi-role authentication with JWT
• Role-based access control across Owner, Manager, and Technician
• Company, team, and customer management
• Full work-order lifecycle
• Attendance with GPS capture
• Offline-first sync queue
• Dashboard with operational summaries
• Localisation framework wired up
• PWA support
• Before/after photo uploads
• PDF service report generation
• Company branding foundation
• Audit logging on the backend
• API validation and error handling

Currently being built:

• Completing full multilingual coverage (some screens still have hardcoded strings)
• Dashboard branding polish
• Company logo management flow
• Service report enhancements
• WhatsApp-first report sharing (since that is how most of these businesses already share things)
• Push notification infrastructure
• Production QA and hardening
• Fixing a few stale-state sync edge cases

So overall it is in the polishing phase — not feature-incomplete, but not yet pilot-ready either.

---

Why I am building this

Walk into almost any small service business in India — pest control, electrical, plumbing, AC service, cleaning, security — and you will see the same thing. Daily operations run on WhatsApp groups, paper attendance registers, spreadsheets, and phone calls. The owner is firefighting all day. The manager has no real visibility. The technician has no proper way to log what happened on site.

There are enterprise tools for this, but they are either too expensive or too complicated for a 10-50 person business. TeamShastra is meant to sit in that gap — simple, affordable, mobile-first, designed for actual field operations, not for a head-office user sitting at a desk.

---

Why Flutter, and why now

My day-to-day stack is Next.js and TypeScript. So picking Flutter was a deliberate choice. Three reasons:

1. One codebase, both platforms — Android is the priority for the field users, but managers and owners often use iPhones. React Native was an option, but Flutter's rendering and offline story felt more solid for this use case.
2. PWA fallback comes almost free — useful for desktop dashboards without building a separate web app right now.
3. It is a good forcing function — if I am going to learn a new framework, doing it on a real product is the fastest way.

Being a non-native Flutter developer would normally slow things down a lot. That is where AI tools come in.

---

How AI tools fit into my workflow

I am using AI heavily in this build, and I am not going to pretend otherwise. Here is the honest split:

• GitHub Copilot — autocompletes most of the Dart boilerplate, widget trees, Riverpod providers, and repository methods. Saves me hours of looking up Flutter-specific syntax I do not have in my muscle memory yet.
• ChatGPT — for "how do I do X in Flutter" questions, debugging stack traces, generating test scaffolding, and explaining unfamiliar packages.
• Claude — for code reviews, audits of larger files, and second-opinion checks on architecture decisions.

What I still do myself:

• All architecture and product decisions — offline-first, sync strategy, RBAC model, data shape
• Code review of anything AI generates — nothing goes in untouched
• Tradeoffs and scope decisions — what to build, what to skip
• Debugging the hard bugs — the ones AI cannot reason about because they need product context

Lesson so far: AI tools are a force multiplier, not a replacement. They let me move at the speed of a Flutter developer even though I am still learning the framework, but the architecture quality is still on me. If you let the AI make the design decisions, you end up with a working app that you cannot maintain.

---

How it is being built

State management with Riverpod

Picked Riverpod over Bloc and Provider mainly because the mental model is closest to how I think about state in React — small, composable, testable units. Repository pattern sits underneath, so the UI never touches the API or the local store directly.

Lesson so far: Coming from React + hooks, Riverpod felt natural in about a day. Worth the small learning curve.

Offline-first sync queue

Every mutation goes into a local queue first, then gets flushed to the backend when the network is available. Conflict resolution is last-write-wins for most things, with stricter rules for attendance and work-order status changes.

Lesson so far: The hard part is not the queue — it is the UI honestly telling the user "this is saved locally, not yet synced". Without that signal, users panic.

FastAPI on the backend

Plain REST, JWT auth, RBAC enforced at the route layer. SQLAlchemy on Postgres. Audit logging on every mutating endpoint so I can trace exactly who changed what.

Lesson so far: Boring backend is good backend. For a workforce app, predictability beats cleverness every time.

Reports and WhatsApp-first sharing

Service reports are generated as PDFs on the backend, stored in cloud storage, and the app gives the technician a one-tap "Share on WhatsApp" button. This matches how these businesses already work — fighting that behaviour would be a losing battle.

Lesson so far: Build for how people actually work, not how you wish they worked.

---

Things I am currently figuring out

• Localisation strategy — should I ship with two or three languages on day one and expand later, or wait until full coverage is done? Leaning towards shipping with English + Hindi first.
• Push notification provider — Firebase Cloud Messaging is the obvious choice, but I am weighing the lock-in vs the convenience.
• Address autocomplete — Google Places is accurate but expensive at scale. MapMyIndia or OpenStreetMap-based options are cheaper but rougher. Still evaluating.
• Dashboard sync — there are some stale-state issues when a manager has the dashboard open while technicians are updating things in parallel. Probably needs a lightweight poll-or-refresh strategy since I am avoiding websockets for now.
• Pricing model — per-user, per-team, or flat-tier. This is more a business question than a technical one, but it will affect how I model billing.

---

What's next

Short term (before pilot):

1. Finish multilingual coverage on the remaining screens
2. Ship Firebase push notifications for work-order assignment and status changes
3. Add address autocomplete and basic map integration
4. Close out the dashboard sync edge cases
5. End-to-end QA across both platforms

Medium term (post-pilot):

1. Pilot deployment with 2-3 real businesses for real-world feedback
2. Advanced reporting and analytics
3. Customer-facing service history portal
4. Operational insights dashboard for owners
5. Public-facing marketing website

---

What I want to avoid

• Becoming a generic CRM — TeamShastra is for field operations, not sales pipelines or marketing automation. Saying no to feature creep is half the job.
• Realtime everything — websockets, live cursors, fancy presence indicators. Adds complexity, drains battery, and the users do not need it.
• Heavy enterprise UI — settings inside settings inside settings. The product has to be usable by a technician with one hand on a bike helmet.
• Vendor lock-in where it does not buy anything — using cloud-agnostic storage and standard auth means I can move infra without a rewrite.

---

Closing note

TeamShastra is very much a moving target right now — the architecture is solid, the core features work, but the last 20% of polish always takes the longest. The plan is to keep this writeup updated as the project moves from polishing into pilot and then into real use. For a web developer building a mobile app with AI as a co-pilot, this has been the most useful experiment I have run in a long time.