# jhonycreativo/pos-platform-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/jhonycreativo/pos-platform-microservices
- Repository: https://github.com/jhonycreativo/pos-platform-microservices

## Overview

This repository is a NestJS microservices application with a Next.js web client: the visible backend flow covers login, token creation, gateway-proxied user operations, and user persistence. User permissions and role/permission administration are distinct domain capabilities. The web tree shows login and dashboard pages, but sampled evidence does not establish their API calls. Backend service calls and persistence are supported by excerpts; unsampled proxy-to-service links are left out.

Main entry points: [`apps/gateway-api/src/modules/users/users.controller.ts`](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/users/users.controller.ts) (Gateway routes), [`apps/auth-service/src/auth/auth.service.ts`](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/auth-service/src/auth/auth.service.ts) (Login service), [`apps/users-service/src/users/users.controller.ts`](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/users/users.controller.ts) (User controller), [`apps/users-service/src/users/users.service.ts`](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/users/users.service.ts) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_login_ui["Login page<br/>[page.tsx]"]
  node_dashboard["Dashboard pages"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_gateway["API gateway"]
  node_gateway_routes["Gateway routes"]
  node_user_proxy["User proxy<br/>[users.proxy.ts]"]
  node_auth_routes["Auth routes<br/>[auth.controller.ts]"]
  node_auth_proxy["Auth proxy<br/>[auth.proxy.ts]"]
  node_jwt_guard["JWT guard<br/>[jwt.guard.ts]"]
  node_jwt_strategy["JWT strategy<br/>[jwt.strategy.ts]"]
end

subgraph group_auth["Authentication"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Login service<br/>[auth.service.ts]"]
end

subgraph group_users["User domain"]
  node_user_controller["User controller"]
  node_user_service["User service<br/>[users.service.ts]"]
  node_roles["Role administration"]
  node_permissions["Permission administration"]
end

subgraph group_persistence["Persistence"]
  node_prisma["Prisma adapter<br/>[prisma.service.ts]"]
  node_postgres[("PostgreSQL")]
end

node_person(("User"))

node_person -->|"enters credentials"| node_login_ui
node_person -->|"views dashboard"| node_dashboard
node_auth_routes -->|"delegates to"| node_auth_proxy
node_gateway_routes -->|"delegates to"| node_user_proxy
node_gateway_routes -->|"guards routes"| node_jwt_guard
node_auth_controller -->|"calls login"| node_auth_service
node_auth_service -->|"requests credentials and permissions"| node_user_controller
node_user_controller -->|"delegates requests"| node_user_service
node_user_service -->|"reads and writes"| node_prisma
node_prisma -->|"connects through adapter"| node_postgres

click node_login_ui "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/web/src/app/login/page.tsx"
click node_dashboard "https://github.com/jhonycreativo/pos-platform-microservices/tree/main/apps/web/src/app/(dashboard)"
click node_web_api "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/web/src/lib/api.ts"
click node_gateway_routes "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/users/users.controller.ts"
click node_user_proxy "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/users/users.proxy.ts"
click node_auth_routes "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/auth/auth.controller.ts"
click node_auth_proxy "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/auth/auth.proxy.ts"
click node_jwt_guard "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/security/jwt.guard.ts"
click node_jwt_strategy "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/security/jwt.strategy.ts"
click node_auth_controller "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/auth-service/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/auth-service/src/auth/auth.service.ts"
click node_user_controller "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/users/users.controller.ts"
click node_user_service "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/users/users.service.ts"
click node_roles "https://github.com/jhonycreativo/pos-platform-microservices/tree/main/apps/users-service/src/roles"
click node_permissions "https://github.com/jhonycreativo/pos-platform-microservices/tree/main/apps/users-service/src/permissions"
click node_prisma "https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/prisma/prisma.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_login_ui,node_dashboard,node_web_api,node_person toneBlue
class node_gateway_routes,node_user_proxy,node_auth_routes,node_auth_proxy,node_jwt_guard,node_jwt_strategy toneAmber
class node_auth_controller,node_auth_service toneMint
class node_user_controller,node_user_service,node_roles,node_permissions toneRose
class node_prisma,node_postgres toneIndigo
```

## Components

### Web client

- [Login page](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/web/src/app/login/page.tsx): `apps/web/src/app/login/page.tsx`
- [Dashboard pages](https://github.com/jhonycreativo/pos-platform-microservices/tree/main/apps/web/src/app/(dashboard)): `apps/web/src/app/(dashboard)`
- [API client](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API gateway

- [Gateway routes](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/users/users.controller.ts): `apps/gateway-api/src/modules/users/users.controller.ts`
- [User proxy](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/users/users.proxy.ts): `apps/gateway-api/src/modules/users/users.proxy.ts`
- [Auth routes](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/auth/auth.controller.ts): `apps/gateway-api/src/modules/auth/auth.controller.ts`
- [Auth proxy](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/modules/auth/auth.proxy.ts): `apps/gateway-api/src/modules/auth/auth.proxy.ts`
- [JWT guard](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/security/jwt.guard.ts): `apps/gateway-api/src/security/jwt.guard.ts`
- [JWT strategy](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/gateway-api/src/security/jwt.strategy.ts): `apps/gateway-api/src/security/jwt.strategy.ts`

### Authentication

- [Auth controller](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/auth-service/src/auth/auth.controller.ts): `apps/auth-service/src/auth/auth.controller.ts`
- [Login service](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/auth-service/src/auth/auth.service.ts): `apps/auth-service/src/auth/auth.service.ts`

### User domain

- [User controller](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/users/users.controller.ts): `apps/users-service/src/users/users.controller.ts`
- [User service](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/users/users.service.ts): `apps/users-service/src/users/users.service.ts`
- [Role administration](https://github.com/jhonycreativo/pos-platform-microservices/tree/main/apps/users-service/src/roles): `apps/users-service/src/roles`
- [Permission administration](https://github.com/jhonycreativo/pos-platform-microservices/tree/main/apps/users-service/src/permissions): `apps/users-service/src/permissions`

### Persistence

- [Prisma adapter](https://github.com/jhonycreativo/pos-platform-microservices/blob/main/apps/users-service/src/prisma/prisma.service.ts): `apps/users-service/src/prisma/prisma.service.ts`
- **PostgreSQL**

### Other components

- **User**

## Connections

- User → Login page: enters credentials (evidence: `apps/web/src/app/login/page.tsx`)
- User → Dashboard pages: views dashboard (evidence: `apps/web/src/app/(dashboard)/page.tsx`)
- Auth routes → Auth proxy: delegates to (evidence: `apps/gateway-api/src/modules/auth/auth.controller.ts`)
- Gateway routes → User proxy: delegates to (evidence: `apps/gateway-api/src/modules/users/users.controller.ts`)
- Gateway routes → JWT guard: guards routes (evidence: `apps/gateway-api/src/modules/users/users.controller.ts`)
- Auth controller → Login service: calls login (evidence: `apps/auth-service/src/auth/auth.controller.ts`)
- Login service → User controller: requests credentials and permissions (evidence: `apps/auth-service/src/auth/auth.service.ts`)
- User controller → User service: delegates requests (evidence: `apps/users-service/src/users/users.controller.ts`)
- User service → Prisma adapter: reads and writes (evidence: `apps/users-service/src/users/users.service.ts`)
- Prisma adapter → PostgreSQL: connects through adapter (evidence: `apps/users-service/src/prisma/prisma.service.ts`)
