appmobiliza/platform

1. Repository shape

- This is a Turborepo-style monorepo with three runtime apps and several shared packages.

- The architecture is intentionally split so that UI apps stay thin and most cross-cutting logic lives in shared packages.

2. Primary client surfaces

- apps/mobile is the field/operator app built with Expo + React Native.

- apps/web is the admin/operations dashboard built with Next.js.

- Both clients consume the same backend and shared contract types, so they present different UIs over a common business model.

3. Backend boundary

- apps/api is the central HTTP service, using Hono, tRPC, and Better Auth.

- It exposes feature routers for profiles, requests, locations, favorites, metrics, notifications, settings, and shift logs.

- This service is the main orchestration layer between the clients, the database, auth, and realtime integrations.

4. Shared API contract layer

- packages/contracts holds the request/response shapes, enums, and Zod schemas shared by all apps.

- This package is the main type-safety boundary: clients and backend agree on the same domain vocabulary here.

- It reduces drift between the mobile app, dashboard, and API router payloads.

5. Business logic layer

- packages/domain contains the core domain rules and use cases, such as request creation, request timeouts, scholar history, favorites, and metric export.

- The API routes should be understood as transport adapters around this layer rather than the place where business rules live.

- For an architecture diagram, this is the key “application logic” tier between API transport and persistence.

6. Persistence layer

- packages/db owns PostgreSQL access via Drizzle ORM, schema definitions, and migrations.

- The schema is organized by domain areas like auth, profiles, requests, settings, locations, and extras.

- packages/seed provides controlled data generation for local/dev datasets and likely supports test or bootstrap flows.

7. Authentication boundary

- packages/auth centralizes Better Auth integration for client, server, and proxy use cases.

- apps/web and apps/mobile both rely on this shared auth layer rather than implementing separate auth stacks.

- The API also depends on it, so auth is a cross-application concern rather than a per-app feature.

8. Realtime and presence

- packages/realtime abstracts multiple realtime providers through client/server adapters.

- It supports provider-specific implementations such as Ably, Pusher, Supabase, WebSocket, and mock adapters.

- This package sits alongside the API and clients to handle live updates like position, attendance, or request status changes.

9. Environment and configuration

- packages/env is the single source of truth for environment variable validation and access.

- The repo avoids direct process.env access from apps/packages and routes all config through this package.

- This is an important deployment boundary because it normalizes local, staging, and hosted environments.

10. Mobile app structure

- The mobile app is organized around route-driven screens, feature hooks, local stores, and reusable UI primitives.

- Its key flows include authentication, onboarding, profile setup, request creation, travel/navigation, history, and scholar/student-specific views.

- It also contains map and location logic, route calculation helpers, and realtime position broadcasting, which suggests the mobile app is responsible for live field operations.

11. Web dashboard structure

- The web app is organized as an admin dashboard with pages for atendimento, bolsistas, estudantes, relatórios, and configuration.

- It uses shared UI building blocks, detail sidebars, date filters, charts, and dashboard-specific stores/components.

- The dashboard is the primary operational console for managing users, locations, shifts, and reporting rather than performing field tasks.

12. Data flow across the system

- The common flow is: mobile/web client -> API router -> domain use case -> database and/or realtime integration -> response back through shared contracts.

- Some client features also interact with external services directly, such as location/routing helpers and realtime transport abstractions.

- Because contracts, auth, and env are shared, the system’s main architectural constraint is consistency across all three app surfaces.

13. Tooling and repo-wide boundaries

- TypeScript is the lingua franca across the monorepo, with shared config presets under config/typescript.

- Biome handles formatting/linting, and Turbo coordinates builds and checks across packages.

- Tests are present at multiple layers, including API router/security tests, mobile component tests, and realtime adapter tests, showing a strong emphasis on contract and behavior verification.

14. How to draw it

- A clean diagram would place apps/mobile and apps/web as separate clients at the top, both pointing to apps/api.

- Under the API, show packages/auth, packages/contracts, packages/domain, packages/db, packages/realtime, and packages/env as shared dependencies.

- Put PostgreSQL/Neon beneath packages/db, and external realtime providers beneath packages/realtime.