# samar-m3/petmate architecture

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

- Interactive diagram: https://gitdiagram.com/samar-m3/petmate
- Repository: https://github.com/samar-m3/petmate

## Overview

PetMate is a Flutter pet-care client backed by an Express/Prisma API. The evidenced end-to-end flow is authentication: an owner registers or logs in through the app, the API validates and handles the request, and the service reads or writes user records before returning a token and safe profile. README capabilities also include veterinary appointments, community events, pet matching, and a marketplace, but their implementation is not present in the supplied source excerpts; those branches are shown as documented, unverified client capabilities.

Main entry points: [`backend/src/modules/auth/auth.routes.ts`](https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.routes.ts) (Auth routes), [`backend/src/config/db.ts`](https://github.com/samar-m3/petmate/blob/main/backend/src/config/db.ts) (Prisma client), [`backend/src/app.ts`](https://github.com/samar-m3/petmate/blob/main/backend/src/app.ts) (Express app), [`backend/src/modules/auth/auth.controller.ts`](https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.controller.ts) (Auth controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_entry["App entry<br/>[main.dart]"]
  node_mobile_auth["Auth screens<br/>[login_page.dart]"]
  node_auth_provider["Auth state<br/>[auth_provider.dart]"]
  node_auth_repository["Auth repository"]
  node_api_client["API client<br/>[api_client.dart]"]
  node_care_appointments["Vet appointments"]
  node_care_events["Community events"]
  node_pet_matching["Pet matching"]
  node_marketplace["Marketplace"]
end

subgraph group_api["API runtime"]
  node_server["HTTP server<br/>[server.ts]"]
  node_express_app["Express app<br/>[app.ts]"]
  node_error_handler["Error handling<br/>[errorHandler.ts]"]
  node_api_response["Response envelopes<br/>[apiResponse.ts]"]
end

subgraph group_auth["Authentication"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_auth_validation["Input validation<br/>[auth.validation.ts]"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_auth_middleware["JWT middleware<br/>[auth.middleware.ts]"]
end

subgraph group_persistence["Persistence"]
  node_db_config["Prisma client<br/>[db.ts]"]
  node_user_store[("User records<br/>[schema.prisma]")]
  node_env_config["Environment config<br/>[env.ts]"]
end

node_owner(("Pet owner"))

node_owner -->|"uses"| node_mobile_auth
node_mobile_entry -.->|"opens"| node_mobile_auth
node_mobile_auth -.->|"updates"| node_auth_provider
node_auth_provider -.->|"delegates to"| node_auth_repository
node_auth_repository -.->|"requests through"| node_api_client
node_api_client -->|"calls API"| node_server
node_owner -.->|"books care"| node_care_appointments
node_owner -.->|"joins events"| node_care_events
node_owner -.->|"seeks matches"| node_pet_matching
node_owner -.->|"shops"| node_marketplace
node_server -->|"serves"| node_express_app
node_express_app -->|"mounts"| node_auth_routes
node_auth_routes -->|"validates with"| node_auth_validation
node_auth_routes -->|"dispatches to"| node_auth_controller
node_auth_routes -->|"guards profile"| node_auth_middleware
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"queries"| node_db_config
node_db_config -.->|"persists users"| node_user_store
node_auth_service -->|"reads JWT config"| node_env_config
node_auth_middleware -->|"loads user"| node_db_config
node_express_app -->|"handles errors"| node_error_handler
node_error_handler -->|"sends errors"| node_api_response
node_auth_controller -->|"sends results"| node_api_response
node_db_config -->|"reads database URL"| node_env_config

click node_mobile_entry "https://github.com/samar-m3/petmate/blob/main/lib/main.dart"
click node_mobile_auth "https://github.com/samar-m3/petmate/blob/main/lib/features/auth/presentation/pages/login_page.dart"
click node_auth_provider "https://github.com/samar-m3/petmate/blob/main/lib/features/auth/presentation/providers/auth_provider.dart"
click node_auth_repository "https://github.com/samar-m3/petmate/blob/main/lib/features/auth/data/repositories/auth_repository.dart"
click node_api_client "https://github.com/samar-m3/petmate/blob/main/lib/core/services/api_client.dart"
click node_care_appointments "https://github.com/samar-m3/petmate/tree/main/lib/features/care_events/screens/appointments"
click node_care_events "https://github.com/samar-m3/petmate/tree/main/lib/features/care_events/screens/events"
click node_pet_matching "https://github.com/samar-m3/petmate/tree/main/lib/features"
click node_marketplace "https://github.com/samar-m3/petmate/tree/main/lib/features"
click node_server "https://github.com/samar-m3/petmate/blob/main/backend/src/server.ts"
click node_express_app "https://github.com/samar-m3/petmate/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.routes.ts"
click node_auth_validation "https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.validation.ts"
click node_auth_controller "https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.service.ts"
click node_auth_middleware "https://github.com/samar-m3/petmate/blob/main/backend/src/middleware/auth.middleware.ts"
click node_error_handler "https://github.com/samar-m3/petmate/blob/main/backend/src/middleware/errorHandler.ts"
click node_api_response "https://github.com/samar-m3/petmate/blob/main/backend/src/utils/apiResponse.ts"
click node_db_config "https://github.com/samar-m3/petmate/blob/main/backend/src/config/db.ts"
click node_user_store "https://github.com/samar-m3/petmate/blob/main/backend/prisma/schema.prisma"
click node_env_config "https://github.com/samar-m3/petmate/blob/main/backend/src/config/env.ts"

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_mobile_entry,node_mobile_auth,node_auth_provider,node_auth_repository,node_api_client,node_care_appointments,node_care_events,node_pet_matching,node_marketplace toneBlue
class node_server,node_express_app,node_error_handler,node_api_response toneAmber
class node_auth_routes,node_auth_validation,node_auth_controller,node_auth_service,node_auth_middleware toneMint
class node_db_config,node_user_store,node_env_config toneRose
class node_owner toneIndigo
```

## Components

### Mobile app

- [App entry](https://github.com/samar-m3/petmate/blob/main/lib/main.dart): `lib/main.dart`
- [Auth screens](https://github.com/samar-m3/petmate/blob/main/lib/features/auth/presentation/pages/login_page.dart): `lib/features/auth/presentation/pages/login_page.dart`
- [Auth state](https://github.com/samar-m3/petmate/blob/main/lib/features/auth/presentation/providers/auth_provider.dart): `lib/features/auth/presentation/providers/auth_provider.dart`
- [Auth repository](https://github.com/samar-m3/petmate/blob/main/lib/features/auth/data/repositories/auth_repository.dart): `lib/features/auth/data/repositories/auth_repository.dart`
- [API client](https://github.com/samar-m3/petmate/blob/main/lib/core/services/api_client.dart): `lib/core/services/api_client.dart`
- [Vet appointments](https://github.com/samar-m3/petmate/tree/main/lib/features/care_events/screens/appointments): `lib/features/care_events/screens/appointments`
- [Community events](https://github.com/samar-m3/petmate/tree/main/lib/features/care_events/screens/events): `lib/features/care_events/screens/events`
- [Pet matching](https://github.com/samar-m3/petmate/tree/main/lib/features): `lib/features`
- [Marketplace](https://github.com/samar-m3/petmate/tree/main/lib/features): `lib/features`

### API runtime

- [HTTP server](https://github.com/samar-m3/petmate/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Express app](https://github.com/samar-m3/petmate/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Error handling](https://github.com/samar-m3/petmate/blob/main/backend/src/middleware/errorHandler.ts): `backend/src/middleware/errorHandler.ts`
- [Response envelopes](https://github.com/samar-m3/petmate/blob/main/backend/src/utils/apiResponse.ts): `backend/src/utils/apiResponse.ts`

### Authentication

- [Auth routes](https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.routes.ts): `backend/src/modules/auth/auth.routes.ts`
- [Input validation](https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.validation.ts): `backend/src/modules/auth/auth.validation.ts`
- [Auth controller](https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.controller.ts): `backend/src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/samar-m3/petmate/blob/main/backend/src/modules/auth/auth.service.ts): `backend/src/modules/auth/auth.service.ts`
- [JWT middleware](https://github.com/samar-m3/petmate/blob/main/backend/src/middleware/auth.middleware.ts): `backend/src/middleware/auth.middleware.ts`

### Persistence

- [Prisma client](https://github.com/samar-m3/petmate/blob/main/backend/src/config/db.ts): `backend/src/config/db.ts`
- [User records](https://github.com/samar-m3/petmate/blob/main/backend/prisma/schema.prisma): `backend/prisma/schema.prisma`
- [Environment config](https://github.com/samar-m3/petmate/blob/main/backend/src/config/env.ts): `backend/src/config/env.ts`

### Other components

- **Pet owner**

## Connections

- Pet owner → Auth screens: uses (evidence: `README.md`)
- App entry → Auth screens: opens
- Auth screens → Auth state: updates
- Auth state → Auth repository: delegates to
- Auth repository → API client: requests through
- API client → HTTP server: calls API (evidence: `README.md`)
- Pet owner → Vet appointments: books care
- Pet owner → Community events: joins events
- Pet owner → Pet matching: seeks matches
- Pet owner → Marketplace: shops
- HTTP server → Express app: serves (evidence: `backend/src/server.ts`)
- Express app → Auth routes: mounts (evidence: `backend/src/app.ts`)
- Auth routes → Input validation: validates with (evidence: `backend/src/modules/auth/auth.routes.ts`)
- Auth routes → Auth controller: dispatches to (evidence: `backend/src/modules/auth/auth.routes.ts`)
- Auth routes → JWT middleware: guards profile (evidence: `backend/src/modules/auth/auth.routes.ts`)
- Auth controller → Auth service: calls (evidence: `backend/src/modules/auth/auth.controller.ts`)
- Auth service → Prisma client: queries (evidence: `backend/src/modules/auth/auth.service.ts`)
- Prisma client → User records: persists users
- Auth service → Environment config: reads JWT config (evidence: `backend/src/modules/auth/auth.service.ts`)
- JWT middleware → Prisma client: loads user (evidence: `backend/src/middleware/auth.middleware.ts`)
- Express app → Error handling: handles errors (evidence: `backend/src/app.ts`)
- Error handling → Response envelopes: sends errors (evidence: `backend/src/middleware/errorHandler.ts`)
- Auth controller → Response envelopes: sends results (evidence: `backend/src/modules/auth/auth.controller.ts`)
- Prisma client → Environment config: reads database URL (evidence: `backend/src/config/db.ts`)
