# winnerolusola/trekka architecture

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

- Interactive diagram: https://gitdiagram.com/winnerolusola/trekka
- Repository: https://github.com/winnerolusola/trekka

## Overview

Trekka combines a Flutter client, a NestJS API, and Hedera-based services for a privacy-conscious peer-to-peer product. The principal evidenced runtime path is email OTP authentication and ride hailing: the client calls API endpoints, the API coordinates account and ride operations, and wallet operations can execute ride-contract transactions. The README also documents marketplace, recycling, quests, courier, and decentralized storage capabilities. Mobile and contract internals, and several API service implementations, are not present in the sampled source, so those branches use only supported package paths and documented links.

Main entry points: [`packages/trekka-mobile`](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-mobile) (Trekka Mobile), [`packages/trekka-api/src/auth/auth.service.ts`](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/auth.service.ts) (Auth Coordination), [`packages/trekka-api/src/wallets/wallets.service.ts`](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/wallets.service.ts) (Wallet Service), [`packages/trekka-api/src/logistics/logistics.service.ts`](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/logistics/logistics.service.ts) (Hailing Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_mobile["Trekka Mobile"]
end

subgraph group_identity["Identity"]
  node_auth_controller["Auth Endpoints<br/>[auth.controller.ts]"]
  node_auth_service["Auth Coordination<br/>[auth.service.ts]"]
  node_otp["OTP Service<br/>[otp.service.ts]"]
  node_tokens["Token Service<br/>[token.service.ts]"]
  node_users["User Service<br/>[users.service.ts]"]
  node_email["Email Service<br/>[email.service.ts]"]
  node_database[("Postgres")]
end

subgraph group_product["API Product Services"]
  node_logistics_controller["Hailing Endpoints"]
  node_logistics["Hailing Service"]
  node_wallet_controller["Wallet Endpoints"]
  node_wallets["Wallet Service<br/>[wallets.service.ts]"]
  node_encryption["Key Encryption"]
  node_marketplace["Marketplace"]
  node_recycling["Recycling"]
  node_quests["Quest Rewards"]
  node_courier["Courier Delivery"]
end

subgraph group_hedera["Hedera Platform"]
  node_contracts["Hedera Contracts"]
  node_consensus["Consensus Service"]
  node_hedera{{"Hedera Network"}}
  node_mirror["Mirror Nodes"]
  node_ipfs["IPFS Storage"]
end

node_rider(("Rider or Driver"))

node_rider -->|"uses"| node_mobile
node_mobile -->|"requests auth"| node_auth_controller
node_auth_controller -->|"dispatches"| node_auth_service
node_auth_service -->|"finds and updates"| node_users
node_auth_service -->|"creates and validates"| node_otp
node_auth_service -->|"generates and verifies"| node_tokens
node_auth_service -->|"sends messages"| node_email
node_auth_service -->|"ensures wallet"| node_wallets
node_users -->|"reads and writes"| node_database
node_wallets -->|"reads and writes"| node_database
node_wallets -->|"encrypts keys"| node_encryption
node_mobile -->|"requests rides"| node_logistics_controller
node_logistics_controller -->|"dispatches"| node_logistics
node_mobile -->|"requests wallet data"| node_wallet_controller
node_wallet_controller -->|"dispatches"| node_wallets
node_wallets -->|"creates accounts and queries balances"| node_hedera
node_wallets -->|"executes ride transactions"| node_contracts
node_contracts -->|"executes on"| node_hedera
node_logistics -.->|"submits ride summaries"| node_consensus
node_consensus -->|"submits topic messages"| node_hedera
node_contracts -->|"emits events"| node_mirror
node_hedera -->|"replicates messages"| node_mirror
node_mirror -.->|"streams events and transactions"| node_logistics
node_mobile -.->|"uploads media"| node_ipfs
node_ipfs -.->|"serves proofs"| node_mobile
node_ipfs -.->|"serves proof metadata"| node_logistics
node_mobile -.->|"uses marketplace"| node_marketplace
node_mobile -.->|"uses recycling"| node_recycling
node_mobile -.->|"uses quests"| node_quests
node_mobile -.->|"uses courier"| node_courier

click node_mobile "https://github.com/winnerolusola/trekka/tree/main/packages/trekka-mobile"
click node_auth_controller "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/auth.service.ts"
click node_otp "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/otp.service.ts"
click node_tokens "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/token.service.ts"
click node_users "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/users/users.service.ts"
click node_email "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/email/email.service.ts"
click node_logistics_controller "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/logistics/logistics.controller.ts"
click node_logistics "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/logistics/logistics.service.ts"
click node_wallet_controller "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/wallets.controller.ts"
click node_wallets "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/wallets.service.ts"
click node_encryption "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/encryption.service.ts"
click node_marketplace "https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts"
click node_recycling "https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts"
click node_quests "https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts"
click node_courier "https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts"
click node_contracts "https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts"
click node_consensus "https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/hedera/consensus.service.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 toneBlue
class node_auth_controller,node_auth_service,node_otp,node_tokens,node_users,node_email,node_database toneAmber
class node_logistics_controller,node_logistics,node_wallet_controller,node_wallets,node_encryption,node_marketplace,node_recycling,node_quests,node_courier toneMint
class node_contracts,node_consensus,node_hedera,node_mirror,node_ipfs toneRose
class node_rider toneIndigo
```

## Components

### Client

- [Trekka Mobile](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-mobile): `packages/trekka-mobile`

### Identity

- [Auth Endpoints](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/auth.controller.ts): `packages/trekka-api/src/auth/auth.controller.ts`
- [Auth Coordination](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/auth.service.ts): `packages/trekka-api/src/auth/auth.service.ts`
- [OTP Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/otp.service.ts): `packages/trekka-api/src/auth/otp.service.ts`
- [Token Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/auth/token.service.ts): `packages/trekka-api/src/auth/token.service.ts`
- [User Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/users/users.service.ts): `packages/trekka-api/src/users/users.service.ts`
- [Email Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/email/email.service.ts): `packages/trekka-api/src/email/email.service.ts`
- **Postgres**

### API Product Services

- [Hailing Endpoints](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/logistics/logistics.controller.ts): `packages/trekka-api/src/logistics/logistics.controller.ts`
- [Hailing Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/logistics/logistics.service.ts): `packages/trekka-api/src/logistics/logistics.service.ts`
- [Wallet Endpoints](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/wallets.controller.ts): `packages/trekka-api/src/wallets/wallets.controller.ts`
- [Wallet Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/wallets.service.ts): `packages/trekka-api/src/wallets/wallets.service.ts`
- [Key Encryption](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/wallets/encryption.service.ts): `packages/trekka-api/src/wallets/encryption.service.ts`
- [Marketplace](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts): `packages/trekka-contracts`
- [Recycling](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts): `packages/trekka-contracts`
- [Quest Rewards](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts): `packages/trekka-contracts`
- [Courier Delivery](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts): `packages/trekka-contracts`

### Hedera Platform

- [Hedera Contracts](https://github.com/winnerolusola/trekka/tree/main/packages/trekka-contracts): `packages/trekka-contracts`
- [Consensus Service](https://github.com/winnerolusola/trekka/blob/main/packages/trekka-api/src/hedera/consensus.service.ts): `packages/trekka-api/src/hedera/consensus.service.ts`
- **Hedera Network**
- **Mirror Nodes**
- **IPFS Storage**

### Other components

- **Rider or Driver**

## Connections

- Rider or Driver → Trekka Mobile: uses
- Trekka Mobile → Auth Endpoints: requests auth
- Auth Endpoints → Auth Coordination: dispatches
- Auth Coordination → User Service: finds and updates
- Auth Coordination → OTP Service: creates and validates
- Auth Coordination → Token Service: generates and verifies
- Auth Coordination → Email Service: sends messages
- Auth Coordination → Wallet Service: ensures wallet
- User Service → Postgres: reads and writes
- Wallet Service → Postgres: reads and writes
- Wallet Service → Key Encryption: encrypts keys
- Trekka Mobile → Hailing Endpoints: requests rides
- Hailing Endpoints → Hailing Service: dispatches
- Trekka Mobile → Wallet Endpoints: requests wallet data
- Wallet Endpoints → Wallet Service: dispatches
- Wallet Service → Hedera Network: creates accounts and queries balances
- Wallet Service → Hedera Contracts: executes ride transactions
- Hedera Contracts → Hedera Network: executes on
- Hailing Service → Consensus Service: submits ride summaries
- Consensus Service → Hedera Network: submits topic messages
- Hedera Contracts → Mirror Nodes: emits events
- Hedera Network → Mirror Nodes: replicates messages
- Mirror Nodes → Hailing Service: streams events and transactions
- Trekka Mobile → IPFS Storage: uploads media
- IPFS Storage → Trekka Mobile: serves proofs
- IPFS Storage → Hailing Service: serves proof metadata
- Trekka Mobile → Marketplace: uses marketplace
- Trekka Mobile → Recycling: uses recycling
- Trekka Mobile → Quest Rewards: uses quests
- Trekka Mobile → Courier Delivery: uses courier