# appmobiliza/platform architecture

> Architecture diagram of the GitHub repository appmobiliza/platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/appmobiliza/platform
- Repository: https://github.com/appmobiliza/platform

## Overview

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`.

Main entry points: [`apps/api`](https://github.com/appmobiliza/platform/tree/dev/apps/api) (API service), [`apps/mobile`](https://github.com/appmobiliza/platform/tree/dev/apps/mobile) (Mobile app), [`apps/web`](https://github.com/appmobiliza/platform/tree/dev/apps/web) (Web app), [`packages/realtime`](https://github.com/appmobiliza/platform/tree/dev/packages/realtime) (Realtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_apps_mobile["Mobile app<br/>expo client"]
  node_apps_web["Web app<br/>nextjs dashboard"]
  node_apps_api["API service<br/>hono trpc api"]
  node_apps_mobile_routes["Mobile routes<br/>screen flow"]
  node_apps_mobile_state["Mobile state<br/>stores hooks"]
  node_apps_mobile_ui["Mobile UI<br/>components"]
  node_apps_web_routes["Web pages<br/>dashboard routes"]
  node_apps_web_ui["Web UI<br/>dashboard components"]
  node_apps_web_data["Web data<br/>client data layer"]
  node_api_routers["Feature routers<br/>http routes"]
  node_api_tests["API tests<br/>security and router tests"]
end

subgraph group_packages["Shared packages"]
  node_pkg_contracts["Contracts<br/>shared schemas"]
  node_pkg_domain{{"Domain logic<br/>use cases"}}
  node_pkg_db[("Database<br/>drizzle postgres")]
  node_pkg_auth["Auth"]
  node_pkg_realtime["Realtime<br/>adapter layer"]
  node_pkg_env["Env<br/>config validation"]
  node_pkg_trpc["tRPC core<br/>rpc utilities"]
  node_pkg_seed["Seed data<br/>data generator"]
  node_realtime_adapters["Adapters<br/>provider clients"]
  node_db_schema["Schema<br/>domain tables"]
  node_contracts_models["Models<br/>enums and schemas"]
end

subgraph group_external["External systems"]
end

node_apps_mobile -->|"renders"| node_apps_mobile_routes
node_apps_mobile -->|"uses"| node_apps_mobile_ui
node_apps_mobile -->|"depends on"| node_apps_mobile_state
node_apps_web -->|"renders"| node_apps_web_routes
node_apps_web -->|"uses"| node_apps_web_ui
node_apps_web -->|"depends on"| node_apps_web_data
node_apps_mobile_state -->|"auth"| node_pkg_auth
node_apps_web_data -->|"auth"| node_pkg_auth
node_apps_mobile_state -->|"config"| node_pkg_env
node_apps_web_data -->|"config"| node_pkg_env
node_apps_api -->|"auth"| node_pkg_auth
node_apps_api -->|"config"| node_pkg_env
node_apps_api -->|"rpc core"| node_pkg_trpc
node_apps_api -->|"contracts"| node_pkg_contracts
node_apps_api -->|"business logic"| node_pkg_domain
node_apps_api -->|"persistence"| node_pkg_db
node_apps_api -->|"live updates"| node_pkg_realtime
node_apps_api -->|"exposes"| node_api_routers
node_api_routers -->|"validates"| node_pkg_contracts
node_api_routers -->|"calls"| node_pkg_domain
node_api_routers -->|"queries"| node_pkg_db
node_api_routers -->|"notifies"| node_pkg_realtime
node_pkg_domain -->|"reads/writes"| node_pkg_db
node_pkg_domain -->|"domain types"| node_pkg_contracts
node_pkg_db -->|"defines"| node_db_schema
node_pkg_realtime -->|"implements"| node_realtime_adapters
node_pkg_realtime -->|"provider config"| node_pkg_env
node_contracts_models -->|"provides"| node_pkg_contracts
node_db_schema -->|"backs"| node_pkg_db
node_pkg_seed -->|"populates"| node_pkg_db
node_apps_mobile -->|"calls"| node_apps_api
node_apps_web -->|"calls"| node_apps_api
node_apps_mobile -->|"types"| node_pkg_contracts
node_apps_web -->|"types"| node_pkg_contracts
node_apps_mobile -->|"subscribes"| node_pkg_realtime
node_apps_web -->|"subscribes"| node_pkg_realtime

click node_apps_mobile "https://github.com/appmobiliza/platform/tree/dev/apps/mobile"
click node_apps_web "https://github.com/appmobiliza/platform/tree/dev/apps/web"
click node_apps_api "https://github.com/appmobiliza/platform/tree/dev/apps/api"
click node_pkg_contracts "https://github.com/appmobiliza/platform/tree/dev/packages/contracts"
click node_pkg_domain "https://github.com/appmobiliza/platform/tree/dev/packages/domain"
click node_pkg_db "https://github.com/appmobiliza/platform/tree/dev/packages/db"
click node_pkg_auth "https://github.com/appmobiliza/platform/tree/dev/packages/auth"
click node_pkg_realtime "https://github.com/appmobiliza/platform/tree/dev/packages/realtime"
click node_pkg_env "https://github.com/appmobiliza/platform/tree/dev/packages/env"
click node_pkg_trpc "https://github.com/appmobiliza/platform/tree/dev/packages/trpc"
click node_pkg_seed "https://github.com/appmobiliza/platform/tree/dev/packages/seed"
click node_apps_mobile_routes "https://github.com/appmobiliza/platform/tree/dev/apps/mobile/src/app"
click node_apps_mobile_state "https://github.com/appmobiliza/platform/tree/dev/apps/mobile/src/lib"
click node_apps_mobile_ui "https://github.com/appmobiliza/platform/tree/dev/apps/mobile/src/components"
click node_apps_web_routes "https://github.com/appmobiliza/platform/tree/dev/apps/web/app"
click node_apps_web_ui "https://github.com/appmobiliza/platform/tree/dev/apps/web/components"
click node_apps_web_data "https://github.com/appmobiliza/platform/tree/dev/apps/web/lib"
click node_api_routers "https://github.com/appmobiliza/platform/tree/dev/apps/api/src/routers"
click node_api_tests "https://github.com/appmobiliza/platform/tree/dev/apps/api/src/__tests__"
click node_realtime_adapters "https://github.com/appmobiliza/platform/tree/dev/packages/realtime/src/adapters"
click node_db_schema "https://github.com/appmobiliza/platform/tree/dev/packages/db/src/schema"
click node_contracts_models "https://github.com/appmobiliza/platform/tree/dev/packages/contracts/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_apps_mobile,node_apps_web,node_apps_api,node_apps_mobile_routes,node_apps_mobile_state,node_apps_mobile_ui,node_apps_web_routes,node_apps_web_ui,node_apps_web_data,node_api_routers,node_api_tests toneBlue
class node_pkg_contracts,node_pkg_domain,node_pkg_db,node_pkg_auth,node_pkg_realtime,node_pkg_env,node_pkg_trpc,node_pkg_seed,node_realtime_adapters,node_db_schema,node_contracts_models toneAmber
```

## Components

### Apps

Primary runtime surfaces for mobile users, web operators, and API traffic.

- [Mobile app](https://github.com/appmobiliza/platform/tree/dev/apps/mobile): expo client · Field/operator React Native app for onboarding, requests, travel, and live position updates. · `apps/mobile`
- [Web app](https://github.com/appmobiliza/platform/tree/dev/apps/web): nextjs dashboard · Admin and operations console for managing users, shifts, locations, and reports. · `apps/web`
- [API service](https://github.com/appmobiliza/platform/tree/dev/apps/api): hono trpc api · Central HTTP service that orchestrates feature routers, auth, persistence, and realtime. · `apps/api`
- [Mobile routes](https://github.com/appmobiliza/platform/tree/dev/apps/mobile/src/app): screen flow · Route-driven screens for auth, onboarding, profile setup, request creation, history, and travel. · `apps/mobile/src/app`
- [Mobile state](https://github.com/appmobiliza/platform/tree/dev/apps/mobile/src/lib): stores hooks · Client state, realtime hooks, map logic, auth session, and request orchestration. · `apps/mobile/src/lib`
- [Mobile UI](https://github.com/appmobiliza/platform/tree/dev/apps/mobile/src/components): components · Reusable UI primitives and flow components for scholar-facing experiences. · `apps/mobile/src/components`
- [Web pages](https://github.com/appmobiliza/platform/tree/dev/apps/web/app): dashboard routes · Admin pages for atendimentos, bolsistas, estudantes, relatórios, and configuration. · `apps/web/app`
- [Web UI](https://github.com/appmobiliza/platform/tree/dev/apps/web/components): dashboard components · Sidebar, detail panels, charts, settings controls, and reusable dashboard widgets. · `apps/web/components`
- [Web data](https://github.com/appmobiliza/platform/tree/dev/apps/web/lib): client data layer · Dashboard auth, cached data, tRPC server helpers, and derived reporting data. · `apps/web/lib`
- [Feature routers](https://github.com/appmobiliza/platform/tree/dev/apps/api/src/routers): http routes · Profile, request, location, favorite, metrics, notification, settings, and shift-log endpoints. · `apps/api/src/routers`
- [API tests](https://github.com/appmobiliza/platform/tree/dev/apps/api/src/__tests__): security and router tests · Behavioral and security coverage for routers, validation, auth, RBAC, and PII handling. · `apps/api/src/__tests__`

### Shared packages

Cross-cutting domain, auth, data, realtime, and environment logic used by all apps.

- [Contracts](https://github.com/appmobiliza/platform/tree/dev/packages/contracts): shared schemas · Shared request/response shapes, enums, and Zod schemas that define the domain vocabulary. · `packages/contracts`
- [Domain logic](https://github.com/appmobiliza/platform/tree/dev/packages/domain): use cases · Core business rules for request creation, timeouts, scholar history, favorites, and metric export. · `packages/domain`
- [Database](https://github.com/appmobiliza/platform/tree/dev/packages/db): drizzle postgres · PostgreSQL access layer with schema definitions, migrations, and database client helpers. · `packages/db`
- [Auth](https://github.com/appmobiliza/platform/tree/dev/packages/auth): better auth · Shared authentication integration for client, server, and proxy usage. · `packages/auth`
- [Realtime](https://github.com/appmobiliza/platform/tree/dev/packages/realtime): adapter layer · Abstraction over live-update providers for client and server transports. · `packages/realtime`
- [Env](https://github.com/appmobiliza/platform/tree/dev/packages/env): config validation · Single source of truth for validated environment variables and runtime config. · `packages/env`
- [tRPC core](https://github.com/appmobiliza/platform/tree/dev/packages/trpc): rpc utilities · Shared tRPC context and error helpers supporting the API boundary. · `packages/trpc`
- [Seed data](https://github.com/appmobiliza/platform/tree/dev/packages/seed): data generator · Controlled generators for local development and bootstrap datasets. · `packages/seed`
- [Adapters](https://github.com/appmobiliza/platform/tree/dev/packages/realtime/src/adapters): provider clients · Client/server implementations for Ably, Pusher, Supabase, WebSocket, and mock modes. · `packages/realtime/src/adapters`
- [Schema](https://github.com/appmobiliza/platform/tree/dev/packages/db/src/schema): domain tables · Domain-oriented schema modules for auth, profiles, requests, settings, locations, and extras. · `packages/db/src/schema`
- [Models](https://github.com/appmobiliza/platform/tree/dev/packages/contracts/src): enums and schemas · Feature-specific contract modules plus shared enums and validation helpers. · `packages/contracts/src`

## Connections

- Mobile app → Mobile routes: renders · The mobile app hosts its route-driven screens here.
- Mobile app → Mobile UI: uses · Screens compose shared mobile UI primitives and flow components.
- Mobile app → Mobile state: depends on · Mobile UI relies on local stores, hooks, auth, map, and realtime helpers.
- Web app → Web pages: renders · The dashboard is organized as Next.js pages and layouts.
- Web app → Web UI: uses · Pages build on shared dashboard components and controls.
- Web app → Web data: depends on · Web pages rely on auth helpers, tRPC server access, and derived dashboard data.
- Mobile state → Auth: auth · Mobile uses the shared auth client and session flow.
- Web data → Auth: auth · Web uses shared client/server auth integrations.
- Mobile state → Env: config · Mobile reads validated runtime configuration through the shared env layer.
- Web data → Env: config · Web runtime configuration is centralized in the env package.
- API service → Auth: auth · The API delegates authentication concerns to the shared Better Auth layer.
- API service → Env: config · The API consumes validated environment settings from the shared env layer.
- API service → tRPC core: rpc core · The API uses shared tRPC context and error helpers.
- API service → Contracts: contracts · Routers and clients share request/response types and validation schemas.
- API service → Domain logic: business logic · Transport adapters call into domain use cases instead of embedding rules.
- API service → Database: persistence · The API reads and writes through the shared database layer.
- API service → Realtime: live updates · The API emits or coordinates realtime events through shared adapters.
- API service → Feature routers: exposes · Feature routers implement the public API surface.
- Feature routers → Contracts: validates · Routers use shared schemas and enums for payload shape agreement.
- Feature routers → Domain logic: calls · Feature endpoints invoke request, favorite, metrics, and history use cases.
- Feature routers → Database: queries · Routers persist and fetch through the schema-backed database layer.
- Feature routers → Realtime: notifies · Selected flows publish live status and presence changes.
- Domain logic → Database: reads/writes · Domain use cases depend on persisted state and domain tables.
- Domain logic → Contracts: domain types · Use cases align with shared enums and validated shapes.
- Database → Schema: defines · The database package organizes tables and enums by domain area.
- Realtime → Adapters: implements · Client and server adapters provide provider-specific transport implementations.
- Realtime → Env: provider config · Realtime provider selection and credentials are driven by env values.
- Models → Contracts: provides · Feature schemas and enums form the shared business vocabulary.
- Schema → Database: backs · Schema modules back the persisted domain model.
- Seed data → Database: populates · Seed generators create controlled datasets for local and bootstrap use.
- Mobile app → API service: calls · Mobile interacts with the backend for requests, profiles, history, and live state.
- Web app → API service: calls · Web dashboard consumes the backend for operational management and reporting.
- Mobile app → Contracts: types · Mobile aligns UI and service calls with shared contract definitions.
- Web app → Contracts: types · Web aligns dashboard payloads with the same shared contracts.
- Mobile app → Realtime: subscribes · Mobile listens to live position and request status updates.
- Web app → Realtime: subscribes · Dashboard views can reflect live operational changes.