boikzdev/school-bus-tracker

1. Repository shape

This is a pnpm TypeScript monorepo with clear separation between deployable apps and shared libraries. The root config (pnpm-workspace.yaml, tsconfig.base.json) is the main coordination layer for builds, type sharing, and dependency management.

2. Top-level runtime boundaries

There are three main application surfaces under artifacts/:

- api-server: an Express backend service

- bus-tracker: an Expo/React Native client for mobile and web

- mockup-sandbox: a Vite-based UI prototype environment

These are intentionally isolated so they can be deployed and evolved independently.

3. Contract-first API layer

The lib/api-spec package holds the OpenAPI source of truth. From that spec, the repo generates:

- lib/api-zod: runtime validation schemas

- lib/api-client-react: typed React Query client/hooks

This creates a strict boundary between backend and frontend: the API contract is defined once, then projected into both server validation and client consumption.

4. Backend service architecture

artifacts/api-server is a small Express app with a conventional split:

- src/index.ts boots the server

- src/app.ts wires middleware and routes

- src/routes/index.ts centralizes route registration

- src/routes/health.ts provides a liveness endpoint

The backend is designed as a REST layer over the domain, with /api-style routes and a build pipeline (build.ts) for production bundling.

5. Data persistence boundary

Shared database concerns live in lib/db, which is organized around Drizzle ORM and PostgreSQL schema definitions. This keeps schema and database access logic outside the deployable apps, so both the API server and any future services can reuse the same table definitions and connection conventions.

6. Mobile/web client architecture

artifacts/bus-tracker is an Expo app using file-based routing under app/. The key runtime entrypoints are:

- app/_layout.tsx for global composition

- app/(tabs)/_layout.tsx and app/(tabs)/index.tsx for the main tracking experience

- app/+not-found.tsx for routing fallback

This is the primary user-facing surface for live tracking.

7. Realtime location and UI state flow

The central client-side state boundary is context/BusContext.tsx. It appears to aggregate:

- Firebase Realtime Database bus updates

- selected bus state

- user geolocation

- derived values like distance and ETA

This context feeds the rest of the UI, so the app’s visual state is driven by a single realtime data layer rather than many disconnected fetches.

8. Client-side feature composition

The bus tracker UI is decomposed into focused components:

- BusSelector for route/bus selection

- DashboardCard for metrics like distance and ETA

- ArrivingAlert for threshold-based notifications

- ErrorBoundary / ErrorFallback for resilient rendering

That makes the screen architecture event-driven: live data arrives, context updates, the dashboard/map/alert react to it.

9. Platform-specific map boundary

Mapping is abstracted through MapWrapper.tsx plus MapWrapper.web.tsx. That is the key cross-platform seam:

- native iOS/Android can use native map rendering

- web uses a different implementation behind the same interface

This keeps the main screen logic platform-agnostic while allowing different map providers or rendering strategies.

10. External realtime services

Firebase is the most important external integration in the client. It is used for live bus location data, which enables the app’s “real-time” behavior without polling-heavy APIs. The README also indicates Google Maps support for map rendering, which is another major external dependency shaping the client architecture.

11. Prototype and design system sandbox

artifacts/mockup-sandbox is a separate Vite app used for interface exploration and component previewing. Its large components/ui set indicates a design-system-heavy workflow, likely for composing and validating screens before they are copied into the production app.

12. Shared tooling and build model

The repo also includes scripts/ for small TypeScript utilities and monorepo maintenance. Across the whole codebase, the main architectural constraint is consistency: TypeScript project references, generated API artifacts, and workspace-managed packages keep the server, client, and shared libs aligned.

13. How the pieces fit together

The clearest end-to-end flow is:

- bus location updates originate in Firebase

- bus-tracker subscribes through BusContext

- derived distance/ETA/arrival state drives map, dashboard, and alert UI

- backend REST APIs in api-server expose broader application operations

- shared OpenAPI/Zod/client packages keep the API boundary type-safe

In diagram terms, the repo is best modeled as a monorepo with one realtime client path, one REST backend path, and a shared contract/data layer between them.