OneTwo v3 — Backend Developer Brief

Everything you need to know to build the .NET backend for OneTwo's sports field booking platform.

What Is OneTwo?

OneTwo is a direct sports field operator in Al-Qassim, Saudi Arabia. We own and operate 50+ football, volleyball, and padel fields across 15+ locations. We are not a marketplace — we collect all booking revenue directly.

~60
Bookings / Day
Target: 325/day
507
Active Customers
Target: 2,500
212K
SAR / Month
Target: 1,060K
50+
Fields
Target: 250

Why the Rebuild?

The current system (PocketBase + SQLite + Go + Vue 2) has critical problems that block growth:

Problem Impact
58.3% of bookings have zero price Cannot track true revenue — over half of bookings have no price recorded
34.8% stuck in stale status Confirmed sessions still show as "upcoming" weeks later, no auto-progression
Bookings vanish with no trace Top customer complaint. Zero audit trail to investigate what happened
Double-bookings are possible App-level checks only, bypassed by contract generator — 4 data corruption incidents
SQLite single-writer bottleneck Cannot scale beyond current 60 bookings/day; blocks 5x growth target
3+ second admin page loads Causes 54+ rage clicks/day from field managers and admins

What You Are Building

A monolith-first REST API that serves three client applications:

Web Admin Dashboard

Used by admins and executives. Server-rendered web pages. Session/cookie auth.

Field Manager App

Flutter mobile app for on-site staff. Cached schedule, quick booking creation. JWT auth.

Customer App

Flutter mobile app for customers. Browse fields, self-service booking. JWT auth.

Key principle: All three clients share a single service layer to ensure consistent business logic. Web admin controllers and mobile API controllers both call the same underlying services. Never duplicate booking logic across controllers.

Technology Stack

The backend is built on .NET 10 with EF Core and SQL Server. The project (OneTwoApi) already has 16 controllers, 47 models, and EF Core migrations in place.

Concern Requirement Notes
Framework .NET 10 (ASP.NET Core) Controller-based REST API with [ApiController] attribute
Database SQL Server 2022 EF Core 10.0.3 with Microsoft.EntityFrameworkCore.SqlServer
ORM Entity Framework Core Code-first migrations, enums as strings via HasConversion<string>()
Job Queue Hangfire or hosted services 5 scheduled jobs: hold cleanup, auto-complete, auto-cancel, reminders, contract gen
Auth (Web) Session / Cookie For admin dashboard
Auth (Mobile) JWT 24h inactivity timeout, refresh mechanism
API Format JSON:API Standard for mobile endpoints; pagination, filtering, sorting, includes
WhatsApp WAHA + Twilio WAHA self-hosted primary, Twilio automatic fallback
Cache / Queue Redis Job queues and caching
File Storage S3-compatible MinIO in dev, AWS S3 in prod
Analytics PostHog Server-side SDK for custom event dispatch (80+ events)

Non-Functional Requirements

Requirement Target Context
API response time < 200ms reads, < 500ms writes v2 has 285ms interaction delay (Poor)
Admin page load < 1 second v2 takes 3+ seconds with 100+ bookings
Daily booking capacity 325/day 5x current load (60/day)
Uptime 99.5% ~3.6 hours/month downtime allowed
Audit retention Indefinite Never delete audit_logs
Price recording 100% v2 has 58.3% missing — DB constraint enforces this
Stale bookings 0% v2 has 34.8% — auto-progression handles this

Localization & Regional Notes

Language

Arabic-first, RTL is the primary layout direction. All user-facing text must support Arabic.

Phone Numbers

Saudi format: 05XXXXXXXX (10 digits). This is the primary user identifier.

Currency

SAR (Saudi Riyal). No decimal places shown to users. All prices are VAT-inclusive (15%).

Timezone

Asia/Riyadh (UTC+3). No DST. All timestamps stored as TIMESTAMPTZ. Gregorian calendar (not Hijri).

What Makes This Project Unique

1. Database-enforced invariants. The most critical business rules (no double-bookings, mandatory pricing) are enforced at the SQL Server level with UNIQUE indexes, triggers, and CHECK constraints — not just in application code. This is a core architectural principle.
2. Shared service layer. Web admin and mobile API must use the same service classes. No duplicating booking logic in two controllers. Every code path goes through BookingService.
3. Audit everything. Every mutation to bookings, payments, and user data must produce an immutable audit log entry (who, what, when, old value, new value). This is the #1 lesson from v2's "disappearing bookings" problem.
4. WhatsApp is the primary channel. Not email, not push notifications. WhatsApp is how 98% of customers interact. Automating it is the #1 business priority.
5. Field manager scoping. FMs can only see/interact with their assigned fields. This is middleware-enforced, not UI-hidden. Every query must filter by assigned fields.
6. Arabic-first RTL. This is the primary direction, not an afterthought. All interfaces are designed right-to-left first.

Developer Files

Drop these files into your OneTwoApi project root to configure Claude Code and provide comprehensive business rules.

CLAUDE.md

Claude Code project config — coding conventions, architecture rules, business constraints, and what NOT to build. (~120 lines)

spec.md

Comprehensive business rules — booking state machine, auth, RBAC, payments, contracts, scheduling, all 29 entities + 18 enums. (~480 lines)

Growth Targets (12 Months)

Metric v2 Baseline v3 Launch v3 Year-End
Active fields 46 50 250
Locations 15 15 40+
Customers 507 550 2,500
Bookings/day 60.6 65 325
Monthly revenue (SAR) ~212K ~230K ~1,060K