OpenStore | Documentacion Tecnica

Overview

OpenStore usa una arquitectura de microservicios donde cada dominio del negocio se implementa de forma independiente:

user-service: autenticacion, seguridad y usuarios.
shop-service: tiendas y membresias.
product-service: catalogo, disponibilidad e imagenes.

Servicios y puertos

Los puertos varian por entorno. A continuacion se resumen los valores definidos en Docker Compose y CloudFormation.

Servicio	Stack	Puerto host	Puerto interno	Base path
user-service	Spring Boot	3050	8080	/api
shop-service	Express + Prisma	3060	3000	/
product-service	FastAPI	3070	8000	/
store-service	FastAPI	2060	8000	/
postgres	PostgreSQL	${POSTGRES_PORT:-4050}	5432	N/A
mysql	MySQL	${MYSQL_PORT:-4060}	3306	N/A
mongo	MongoDB	${MONGO_PORT:-4070}	27017	N/A

Nota local: si un puerto ya esta en uso (ejemplo 4060), el script SETUP_BD.sh asigna automaticamente el siguiente puerto libre y lo refleja en backend/.env y backend/.env.api.generated.

Componente AWS	Puerto	Detalle
ALB listener	80	Entrada publica HTTP y enrutamiento por path
App servers (EC2)	3050, 3060, 3070, 2060	Reciben trafico desde el SG del ALB
DB server (EC2)	4050, 4060, 4070	Puertos de BD abiertos por Security Group

Stack

React
Spring Boot
FastAPI
Prisma
MySQL
PostgreSQL
MongoDB

Despliegue AWS (CloudFormation + Amplify)

El template cloud-formation.yml aprovisiona ALB, EC2 para apps, EC2 para bases de datos, bucket S3 y el despliegue del frontend en Amplify tomando la carpeta frontend del mismo repositorio.

1. Prerequisitos

AWS CLI configurado (credenciales y region).
VPC y dos subnets publicas en la misma region.
KeyPair existente para las instancias EC2.
Permisos para EC2, ELBv2, S3, CloudFormation y Amplify.

2. Obtener IDs de red y keypair

aws ec2 describe-vpcs \
  --query "Vpcs[].{VpcId:VpcId,Cidr:CidrBlock,Name:Tags[?Key=='Name']|[0].Value}" \
  --output table

aws ec2 describe-subnets \
  --filters "Name=vpc-id,Values=vpc-xxxxxx" \
  --query "Subnets[].{SubnetId:SubnetId,AZ:AvailabilityZone,PublicIpMap:MapPublicIpOnLaunch,Name:Tags[?Key=='Name']|[0].Value}" \
  --output table

aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output table

3. Generar Personal Access Token de GitHub (para Amplify)

Amplify necesita conectarse al repositorio de GitHub para clonar el código y crear webhooks de auto-despliegue. Para ello, requiere un token personal de GitHub (PAT) con permisos específicos.

Pasos para crear el token:

Entra a tu cuenta de GitHub → Settings (engranaje) → Developer settings → Personal access tokens → Tokens (classic)
Haz clic en Generate new token (classic)
Dale un nombre descriptivo, ej: openstore-amplify
Define expiración (recomendado: 30 o 90 días)
Selecciona estos permisos:
- repo (acceso completo a repositorios)
- admin:repo_hook (crear webhooks)
- repo:status (acceso al status del repositorio)
- repo:deployment (gestionar deployments)
Haz clic en Generate token
Copia el token (comienza con ghp_) - GitHub NO lo vuelve a mostrar
Si tu repositorio está en una organización, autoriza el SSO haciendo clic en Configure SSO al lado del token

Guarda este token en un archivo .env en la raíz del proyecto:

FRONTEND_AMPLIFY_ACCESS_TOKEN=ghp_tu_token_aqui

NO commits este archivo a Git. Agrega .env a .gitignore si aún no está.

4. Desplegar stack

Ejemplo (repositorio publico, sin token de GitHub):

aws cloudformation deploy \
  --stack-name openstore-stack \
  --template-file cloud-formation.yml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    InstanceName=MV-OpenShop \
    AMI=ami-08d434e92c0cfa0c0 \
    KeyName=vockey \
    InstanceType=t3.micro \
    VpcId=vpc-xxxxxxxx \
    PublicSubnet1=subnet-xxxxxxxx \
    PublicSubnet2=subnet-yyyyyyyy \
    FrontendRepoUrl=https://github.com/Lazheart/OpenStore \
    FrontendBranchName=main \
    FrontendAmplifyAppName=openstore-frontend

Si Amplify requiere autenticacion GitHub, agrega: FrontendAmplifyAccessToken=ghp_tu_token.

5. Validar outputs

aws cloudformation describe-stacks \
  --stack-name openstore-stack \
  --query "Stacks[0].Outputs[].[OutputKey,OutputValue]" \
  --output table

Outputs esperados: DNS del ALB, URL de Amplify y datos de las instancias.

6. Orden de arranque en backend

El flujo definido en UserData es: primero bases de datos (PostgreSQL, MySQL, MongoDB), luego servicios (user-service, shop-service, product-service) una vez que los puertos de DB estan disponibles.

Como comunicarte con OpenStore

Autenticacion

Para endpoints protegidos usa JWT en cabecera Authorization.

Authorization: Bearer <token_jwt>

Formato de payload

JSON para operaciones comunes.
multipart/form-data cuando subes imagenes en product-service.

Documentacion Swagger

Shop service expone Swagger UI en: http://localhost:3001/api-docs

Endpoints clave

Shop service

GET /health
GET /shops?page=1&limit=10
GET /shops/:id
POST /shops (JWT requerido)
PUT /shops/:id
DELETE /shops/:id
POST /shops/:id/memberships (JWT requerido)

Product service

GET /
GET /shops/:shop_id/products
POST /shops/:shop_id/products (JSON o multipart/form-data)
PATCH /shops/:shop_id/products/:product_id

Ejemplo rapido con curl

curl -X GET "http://localhost:3001/shops?page=1&limit=10"

curl -X POST "http://localhost:8000/shops/{shop_id}/products" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Teclado mecanico",
    "price": 59.99,
    "description": "Switches red",
    "imageUrl": "https://example.com/keyboard.png"
  }'

Diagrama ER

Referencia visual del modelo entidad-relacion usado para usuarios, tiendas y productos.

Reglas de dominio

1. Modelo de Usuarios

Entidad base: User

Campos:

id (PK)
uid (unico)
name
email
phone_number
role (enum: ADMIN, OWNER, CLIENT)

Roles del sistema:

Admin
Owner
Client

Los roles pueden modelarse con herencia o mediante el atributo role.

Restricciones:

Solo usuarios con rol OWNER pueden crear tiendas.
Un OWNER puede tener una o multiples tiendas.
CLIENT y OWNER pueden asociarse a una tienda mediante el campo shop_id.

2. Modelo de Tienda (Shop)

Entidad: Shop

Atributos:

id (PK)
name
owner_id (FK - User.id)

Relaciones:

Un User (OWNER) puede tener muchas Shops (1:N).
Una Shop pertenece a un solo Owner.

3. Modelo de Productos

Entidad: Product

Atributos:

id (PK)
name
price
description
image (URL almacenada en S3)
availability (boolean o enum)
shop_id (FK - Shop.id)

Restricciones:

Un producto solo puede existir si pertenece a una tienda.
Un producto pertenece a una sola tienda.
Dos productos pueden tener el mismo nombre si pertenecen a tiendas diferentes.

Relacion principal: Shop (1) -> (N) Product.