# rovierrhq/rovierr architecture

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

- Interactive diagram: https://gitdiagram.com/rovierrhq/rovierr
- Repository: https://github.com/rovierrhq/rovierr

## Overview

1. **Repository shape**
   - This is a TypeScript monorepo organized around a shared platform for university students.
   - The main runtime surfaces are a **Next.js web app**, an **Expo/React Native app**, a **Tauri desktop app**, a **Bun-based API server**, and a **realtime service**.

2. **Primary product split**
   - The product is not one app; it is a platform with multiple user-facing surfaces:
     - **Web** for the full student platform experience
     - **Native** for mobile access
     - **Desktop** for a lighter companion client
     - **Docs** for public documentation
   - The web app appears to be the most complete client, with routes for academics, career, societies, profile, people, discussions, forms, expenses, roadmap, and login/signup flows.

3. **Backend API boundary**
   - `apps/server` is the central application backend.
   - It is structured as **routers + services + lib helpers**, with routers exposing domain APIs and services holding business logic.
   - The server is built around **oRPC** contracts and uses shared schema definitions from `packages/orpc-contracts`.

4. **Domain modules on the server**
   - The server is divided into feature routers/services such as:
     - academics, calendar, campus feed, career, chat, connection, discussion
     - expenses, forms, people, resume, roadmap
     - society registration, society email, student organizations, tasks, university, user profile
   - This indicates a **modular monolith backend** rather than a single generic API layer.

5. **Shared contract layer**
   - `packages/orpc-contracts` is the API contract boundary shared between clients and server.
   - It contains feature-specific schema modules for the same domains exposed by the backend.
   - This package is the key coupling point that keeps frontend clients aligned with backend request/response shapes.

6. **Persistence layer**
   - `packages/db` defines the database schema, likely via **Drizzle** based on the config and schema layout.
   - The schema is split by domain: auth, users, institutions, programs, courses, academic achievements, campus feed, career, chat, discussion, expenses, forms, roadmap, society registration, tasks, and more.
   - The server reads/writes through this layer; the schema package is the canonical data model boundary.

7. **Data seeding and institutional data**
   - `packages/db-seed` is a separate ingestion/seeding pipeline.
   - It contains structured datasets for institutions, terms, faculties, programs, and a large course catalog, plus scraper infrastructure for collecting institutional data.
   - This package is an offline data-preparation subsystem, not part of request-time serving.

8. **Realtime subsystem**
   - `packages/realtime` is a separate realtime service built around **Centrifugo**.
   - The server has realtime helpers and routers, and the web app has a Centrifugo client integration plus presence hooks.
   - Data flow here is distinct from the main API: the server publishes events, and clients subscribe for presence/chat/feed-like live updates.

9. **Authentication and identity**
   - `packages/auth` provides shared auth clients for web and native, plus permissions logic.
   - The web, native, and desktop apps each have their own auth-client wrappers, but they share the same auth package abstraction.
   - This suggests authentication is centralized, while each client adapts it to its runtime.

10. **Client applications**
   - `apps/web` is the main application frontend, built with **Next.js** and a large component tree for feature-specific screens and dialogs.
   - `apps/native` uses Expo-style routing and platform-specific components for mobile.
   - `apps/desktop` uses **Vite + React + Tauri**, giving a desktop shell over similar app logic.
   - All clients depend on shared UI and contract packages rather than duplicating domain models.

11. **Shared UI and cross-cutting libraries**
   - `packages/ui` provides reusable design-system components, form controls, rich text editor pieces, and visual blocks.
   - `packages/shared` contains common domain-neutral utilities and types used across the platform.
   - These packages form the presentation-layer foundation used by multiple apps.

12. **External service integrations**
   - The server includes integrations for **Google Calendar**, **S3**, **email delivery/templates**, and a separate **Python ID parser** service with a TypeScript client wrapper.
   - These are important boundary services because they extend core platform behavior beyond the database-backed modules.

13. **Operational/deployment topology**
   - The README describes a split deployment model: **Vercel** for frontend hosting, **Cloudflare** for backend API, and **Fly.io** for microservices.
   - Realtime is treated as its own infrastructure component.
   - The repo also includes Docker, Docker Compose, GitHub Actions, and deployment docs, so the system is designed for containerized local development and multi-target deployment.

14. **How data moves through the system**
   - Typical flow: UI in web/native/desktop → shared oRPC contracts → server routers → domain services → DB and external services.
   - Realtime updates follow a separate path through the Centrifugo-based service.
   - Seed data and institutional catalogs are loaded offline into the database, then consumed by runtime APIs and client screens.

15. **Architecture summary for diagramming**
   - Think of this repo as a **multi-client university platform** with:
     - a **shared API contract layer**
     - a **modular backend**
     - a **shared persistence/schema layer**
     - a **dedicated realtime subsystem**
     - and **multiple presentation clients** on web, mobile, and desktop.

Main entry points: [`apps/server`](https://github.com/rovierrhq/rovierr/tree/main/apps/server) (API server), [`packages/orpc-contracts`](https://github.com/rovierrhq/rovierr/tree/main/packages/orpc-contracts) (Contracts), [`apps/web`](https://github.com/rovierrhq/rovierr/tree/main/apps/web) (Web app), [`apps/native`](https://github.com/rovierrhq/rovierr/tree/main/apps/native) (Native app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client surfaces"]
  node_web["Web app<br/>Next.js client"]
  node_native["Native app<br/>Expo client"]
  node_desktop["Desktop app<br/>Tauri shell"]
  node_docs["Docs site<br/>MDX docs"]
end

subgraph group_backend["Backend platform"]
  node_server["API server<br/>Bun API"]
  node_routers["Domain routers<br/>oRPC routes"]
  node_services["Business services<br/>domain logic"]
  node_realtime["Realtime svc<br/>Centrifugo service"]
  node_email["Email service<br/>delivery integration"]
  node_calendar["Calendar integration<br/>Google Calendar"]
  node_s3["Object storage<br/>S3 client"]
end

subgraph group_shared["Shared packages"]
  node_orpc["Contracts<br/>oRPC schemas"]
  node_auth["Auth"]
  node_ui["UI kit<br/>design system"]
  node_sharedlib["Shared utils<br/>common types"]
end

subgraph group_data["Data and infra"]
  node_db[("Database schema<br/>Drizzle models")]
  node_seed["Seed pipeline<br/>offline ingest"]
  node_idparser["ID parser<br/>Python service"]
end

node_web -->|"calls"| node_orpc
node_native -->|"calls"| node_orpc
node_desktop -->|"calls"| node_orpc
node_web -->|"auth"| node_auth
node_native -->|"auth"| node_auth
node_desktop -->|"auth"| node_auth
node_web -->|"renders"| node_ui
node_native -->|"uses"| node_sharedlib
node_desktop -->|"uses"| node_sharedlib
node_server -->|"exposes"| node_routers
node_routers -->|"delegates"| node_services
node_services -->|"reads/writes"| node_db
node_server -->|"implements"| node_orpc
node_orpc -.->|"shapes"| node_db
node_server -->|"publishes"| node_realtime
node_web -->|"subscribes"| node_realtime
node_server -->|"sends"| node_email
node_server -->|"integrates"| node_calendar
node_server -->|"uploads"| node_s3
node_server -->|"calls"| node_idparser
node_seed -->|"loads"| node_db
node_docs -.->|"documents"| node_orpc
node_docs -.->|"describes"| node_web

click node_web "https://github.com/rovierrhq/rovierr/tree/main/apps/web"
click node_native "https://github.com/rovierrhq/rovierr/tree/main/apps/native"
click node_desktop "https://github.com/rovierrhq/rovierr/tree/main/apps/desktop"
click node_docs "https://github.com/rovierrhq/rovierr/tree/main/apps/docs"
click node_server "https://github.com/rovierrhq/rovierr/tree/main/apps/server"
click node_routers "https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/routers"
click node_services "https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/services"
click node_realtime "https://github.com/rovierrhq/rovierr/tree/main/packages/realtime"
click node_orpc "https://github.com/rovierrhq/rovierr/tree/main/packages/orpc-contracts"
click node_auth "https://github.com/rovierrhq/rovierr/tree/main/packages/auth"
click node_ui "https://github.com/rovierrhq/rovierr/tree/main/packages/ui"
click node_sharedlib "https://github.com/rovierrhq/rovierr/tree/main/packages/shared"
click node_db "https://github.com/rovierrhq/rovierr/tree/main/packages/db"
click node_seed "https://github.com/rovierrhq/rovierr/tree/main/packages/db-seed"
click node_idparser "https://github.com/rovierrhq/rovierr/tree/main/packages/id-parser"
click node_email "https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/services/email"
click node_calendar "https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/routers/calendar"
click node_s3 "https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/services/s3"

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_web,node_native,node_desktop,node_docs toneBlue
class node_server,node_routers,node_services,node_realtime,node_email,node_calendar,node_s3 toneAmber
class node_orpc,node_auth,node_ui,node_sharedlib toneMint
class node_db,node_seed,node_idparser toneRose
```

## Components

### Client surfaces

User-facing applications and documentation

- [Web app](https://github.com/rovierrhq/rovierr/tree/main/apps/web): Next.js client · Primary student platform experience with feature-rich routes and screens · `apps/web`
- [Native app](https://github.com/rovierrhq/rovierr/tree/main/apps/native): Expo client · Mobile app with shared auth and oRPC integrations · `apps/native`
- [Desktop app](https://github.com/rovierrhq/rovierr/tree/main/apps/desktop): Tauri shell · Vite/React desktop companion client · `apps/desktop`
- [Docs site](https://github.com/rovierrhq/rovierr/tree/main/apps/docs): MDX docs · Public documentation and API reference · `apps/docs`

### Backend platform

API, realtime, and supporting server-side services

- [API server](https://github.com/rovierrhq/rovierr/tree/main/apps/server): Bun API · Central modular backend exposing domain routers and services · `apps/server`
- [Domain routers](https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/routers): oRPC routes · Backend request boundary organized by feature modules · `apps/server/src/routers`
- [Business services](https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/services): domain logic · Server-side feature logic, integrations, and orchestration · `apps/server/src/services`
- [Realtime svc](https://github.com/rovierrhq/rovierr/tree/main/packages/realtime): Centrifugo service · Separate live-update subsystem for presence and push events · `packages/realtime`
- [Email service](https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/services/email): delivery integration · Templates and sender integration for transactional mail · `apps/server/src/services/email`
- [Calendar integration](https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/routers/calendar): Google Calendar · External calendar boundary used by the backend · `apps/server/src/routers/calendar`
- [Object storage](https://github.com/rovierrhq/rovierr/tree/main/apps/server/src/services/s3): S3 client · File storage boundary for uploads and media · `apps/server/src/services/s3`

### Shared packages

Cross-cutting contracts, auth, UI, and utilities

- [Contracts](https://github.com/rovierrhq/rovierr/tree/main/packages/orpc-contracts): oRPC schemas · Shared API contract boundary used by clients and server · `packages/orpc-contracts`
- [Auth](https://github.com/rovierrhq/rovierr/tree/main/packages/auth): shared auth · Common auth clients and permissions for web and native · `packages/auth`
- [UI kit](https://github.com/rovierrhq/rovierr/tree/main/packages/ui): design system · Reusable components, form controls, and rich text editor pieces · `packages/ui`
- [Shared utils](https://github.com/rovierrhq/rovierr/tree/main/packages/shared): common types · Domain-neutral utilities and shared frontend logic · `packages/shared`

### Data and infra

Persistence, seeding, and external service boundaries

- [Database schema](https://github.com/rovierrhq/rovierr/tree/main/packages/db): Drizzle models · Canonical persistence layer organized by domain schemas · `packages/db`
- [Seed pipeline](https://github.com/rovierrhq/rovierr/tree/main/packages/db-seed): offline ingest · Institutional data ingestion, catalogs, and scraper-based seeding · `packages/db-seed`
- [ID parser](https://github.com/rovierrhq/rovierr/tree/main/packages/id-parser): Python service · External parser service with TypeScript client wrapper · `packages/id-parser`

## Connections

- Web app → Contracts: calls · Web client uses shared API contracts
- Native app → Contracts: calls · Native client uses shared API contracts
- Desktop app → Contracts: calls · Desktop client uses shared API contracts
- Web app → Auth: auth · Web integrates shared auth
- Native app → Auth: auth · Native integrates shared auth
- Desktop app → Auth: auth · Desktop integrates shared auth
- Web app → UI kit: renders · Web builds on shared UI components
- Native app → Shared utils: uses · Native reuses shared utilities
- Desktop app → Shared utils: uses · Desktop reuses shared utilities
- API server → Domain routers: exposes · Server mounts domain routers
- Domain routers → Business services: delegates · Routers delegate to feature services
- Business services → Database schema: reads/writes · Business logic persists through schema layer
- API server → Contracts: implements · Server implements the shared API contract
- Contracts → Database schema: shapes · Contracts align with persistence-backed domain models
- API server → Realtime svc: publishes · Backend emits live events to the realtime service
- Web app → Realtime svc: subscribes · Web listens for presence and live updates
- API server → Email service: sends · Backend triggers transactional email flows
- API server → Calendar integration: integrates · Backend connects to external calendar APIs
- API server → Object storage: uploads · Backend uses object storage for files
- API server → ID parser: calls · Backend delegates ID parsing to external service
- Seed pipeline → Database schema: loads · Offline seeding materializes canonical data into the database
- Docs site → Contracts: documents · Docs publish the public contract surface
- Docs site → Web app: describes · Docs support the main product surface