Skip to content

Commit 7cfec8e

Browse files
Merge pull request #9 from PythonFloripa/feature/single-table-dynamodb
feat: DynamoDB single-table design pattern
2 parents 7dbdd13 + 0db2584 commit 7cfec8e

10 files changed

Lines changed: 791 additions & 362 deletions

‎README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,3 +218,90 @@ Gera uma página para download de um certificado.
218218
- `test_list_user_certificates("alex@example.test", success="false")`
219219
- Testar e-mail com URL encoding:
220220
- `test_list_user_certificates("alex+qa@example.test")`
221+
222+
## DynamoDB Single-Table Design
223+
224+
Este projeto utiliza o padrão DynamoDB Single-Table Design, onde todas as entidades (Orders, Certificates, Products, Participants) são armazenadas em uma única tabela DynamoDB.
225+
226+
### Estrutura da Tabela
227+
228+
| Atributo | Tipo | Descrição |
229+
|----------|------|-----------|
230+
| `PK` | String | Chave de Partição principal |
231+
| `SK` | String | Chave de Ordenação principal |
232+
| `GSI1PK` | String | Chave de Partição do GSI1 |
233+
| `GSI1SK` | String | Chave de Ordenação do GSI1 |
234+
| `GSI2PK` | String | Chave de Partição do GSI2 |
235+
| `GSI2SK` | String | Chave de Ordenação do GSI2 |
236+
| `GSI3PK` | String | Chave de Partição do GSI3 |
237+
| `GSI3SK` | String | Chave de Ordenação do GSI3 |
238+
| `GSI4PK` | String | Chave de Partição do GSI4 |
239+
| `GSI4SK` | String | Chave de Ordenação do GSI4 |
240+
| `EntityType` | String | Tipo da entidade (ORDER, CERTIFICATE, PRODUCT, PARTICIPANT) |
241+
242+
### GSIs (Global Secondary Indexes)
243+
244+
| GSI | Key Schema | Access Pattern |
245+
|-----|------------|----------------|
246+
| GSI1 | `PK: UUID, SK: CERT#` | Certificate by UUID |
247+
| GSI2 | `PK: email, SK: ENTITY#` | Orders, Certificates, Participants by email |
248+
| GSI3 | `PK: product, SK: ENTITY#` | Products by name, Certificates/Orders by product |
249+
| GSI4 | `PK: SUCCESS#Y/N, SK: CERT#` | Successful/Failed certificates |
250+
251+
### Entidades e Keys
252+
253+
#### Certificate
254+
| Key | Value |
255+
|-----|-------|
256+
| PK | `CERTIFICATE#<uuid>` |
257+
| SK | `CERTIFICATE#<uuid>` |
258+
| GSI1PK | `<uuid>` |
259+
| GSI1SK | `CERTIFICATE#<uuid>` |
260+
| GSI2PK | `EMAIL#<normalized_email>` |
261+
| GSI2SK | `CERTIFICATE#<order_id>` |
262+
| GSI3PK | `PRODUCT#<product_id>` |
263+
| GSI3SK | `CERTIFICATE#<order_id>` |
264+
| GSI4PK | `SUCCESS#<true/false>` |
265+
| GSI4SK | `CERTIFICATE#<uuid>` |
266+
267+
#### Order
268+
| Key | Value |
269+
|-----|-------|
270+
| PK | `ORDER#<order_id>` |
271+
| SK | `ORDER#<order_id>` |
272+
| GSI2PK | `EMAIL#<normalized_email>` |
273+
| GSI2SK | `ORDER#<order_id>` |
274+
| GSI3PK | `PRODUCT#<product_id>` |
275+
| GSI3SK | `ORDER#<order_id>` |
276+
277+
#### Product
278+
| Key | Value |
279+
|-----|-------|
280+
| PK | `PRODUCT#<product_id>` |
281+
| SK | `PRODUCT#<product_id>` |
282+
| GSI3PK | `PRODUCT#<product_name>` |
283+
| GSI3SK | `PRODUCT#<product_id>` |
284+
285+
#### Participant
286+
| Key | Value |
287+
|-----|-------|
288+
| PK | `PARTICIPANT#<uuid>` |
289+
| SK | `PARTICIPANT#<uuid>` |
290+
| GSI2PK | `EMAIL#<normalized_email>` |
291+
| GSI2SK | `PARTICIPANT#<uuid>` |
292+
293+
### Normalização de Email
294+
295+
Emails são normalizados para consistência:
296+
- Convertido para minúsculas
297+
- Remoção de pontos antes do `@` (Gmail)
298+
- Remoção de `+` e tudo após
299+
300+
### Repositórios
301+
302+
Cada repositório implementa operações CRUD usando as chaves apropriadas:
303+
304+
- **OrderRepositoryImpl**: GSI2 (email), GSI3 (product)
305+
- **CertificateRepositoryImpl**: GSI1 (UUID), GSI2 (email), GSI3 (product), GSI4 (success)
306+
- **ProductRepositoryImpl**: GSI3 (name)
307+
- **ParticipantRepositoryImpl**: GSI2 (email)
Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
from enum import Enum
2+
from typing import Optional
3+
4+
5+
class EntityType(str, Enum):
6+
ORDER = "ORDER"
7+
PRODUCT = "PRODUCT"
8+
PARTICIPANT = "PARTICIPANT"
9+
CERTIFICATE = "CERTIFICATE"
10+
11+
12+
def pk(entity_type: EntityType, entity_id: str | int) -> str:
13+
return f"{entity_type.value}#{entity_id}"
14+
15+
16+
def sk(entity_type: EntityType, entity_id: str | int) -> str:
17+
return f"{entity_type.value}#{entity_id}"
18+
19+
20+
def sk_order(order_id: int) -> str:
21+
return sk(EntityType.ORDER, order_id)
22+
23+
24+
def sk_product(product_id: int) -> str:
25+
return sk(EntityType.PRODUCT, product_id)
26+
27+
28+
def sk_participant(participant_id: str) -> str:
29+
return sk(EntityType.PARTICIPANT, participant_id)
30+
31+
32+
def sk_certificate(order_id: int) -> str:
33+
return sk(EntityType.CERTIFICATE, order_id)
34+
35+
36+
def gsi1pk_email(email: str) -> str:
37+
return f"EMAIL#{email.lower().strip()}"
38+
39+
40+
def gsi1sk_participant(participant_id: str) -> str:
41+
return f"PARTICIPANT#{participant_id}"
42+
43+
44+
def gsi1sk_order(order_id: int) -> str:
45+
return f"ORDER#{order_id}"
46+
47+
48+
def gsi1sk_certificate(order_id: int) -> str:
49+
return f"CERTIFICATE#{order_id}"
50+
51+
52+
def gsi2pk_product(product_id: int) -> str:
53+
return f"PRODUCT#{product_id}"
54+
55+
56+
def gsi2sk_order(order_id: int) -> str:
57+
return f"ORDER#{order_id}"
58+
59+
60+
def gsi2sk_certificate(order_id: int) -> str:
61+
return f"CERTIFICATE#{order_id}"
62+
63+
64+
def gsi3pk_success(success: bool) -> str:
65+
return f"SUCCESS#{1 if success else 0}"
66+
67+
68+
def gsi3sk_certificate(order_id: int) -> str:
69+
return f"CERTIFICATE#{order_id}"
70+
71+
72+
def gsi1pk_cert_id(cert_id: str) -> str:
73+
return f"CERT#{cert_id}"
74+
75+
76+
def gsi1sk_cert(cert_id: str) -> str:
77+
return f"CERTIFICATE#{cert_id}"
78+
79+
80+
def parse_pk(pk: str) -> tuple[EntityType, str]:
81+
parts = pk.split("#", 1)
82+
if len(parts) != 2:
83+
raise ValueError(f"Invalid PK format: {pk}")
84+
return EntityType(parts[0]), parts[1]
85+
86+
87+
def parse_sk(sk: str) -> tuple[EntityType, str]:
88+
return parse_pk(sk)

‎src/infrastructure/config/config.py‎

Lines changed: 18 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55

66
logger = logging.getLogger(__name__)
77

8-
98
class Config(BaseSettings):
109
REGION: str
1110
BUILDER_QUEUE_URL: str
@@ -14,74 +13,34 @@ class Config(BaseSettings):
1413
PROJECT_NAME: str = Field(default="certified-builder-api-py")
1514
URL_SERVICE_TECH: str
1615
PREFIX_API_VERSION: str = Field(default="/api/v1")
17-
1816
class Config:
1917
env_file = ".env"
2018
env_file_encoding = "utf-8"
21-
19+
2220
@property
23-
def dynamodb_tables(self) -> Dict[str, Dict[str, str]]:
21+
def dynamodb_table(self) -> Dict[str, str]:
2422
"""
25-
Retorna as configurações das tabelas do DynamoDB baseadas no ambiente.
26-
Segue o padrão da infraestrutura Terraform criada.
23+
Retorna a configuração da tabela única do DynamoDB baseada no ambiente.
24+
Single Table Design - todas as entidades em uma única tabela.
2725
"""
2826
base_name = f"{self.PROJECT_NAME}"
2927
environment = self.ENVIRONMENT
30-
28+
3129
return {
32-
"certificates": {
33-
"name": f"{base_name}-certificates-{environment}",
34-
"arn": f"arn:aws:dynamodb:{self.REGION}:*:table/{base_name}-certificates-{environment}",
35-
},
36-
"orders": {
37-
"name": f"{base_name}-orders-{environment}",
38-
"arn": f"arn:aws:dynamodb:{self.REGION}:*:table/{base_name}-orders-{environment}",
39-
},
40-
"participants": {
41-
"name": f"{base_name}-participants-{environment}",
42-
"arn": f"arn:aws:dynamodb:{self.REGION}:*:table/{base_name}-participants-{environment}",
43-
},
44-
"products": {
45-
"name": f"{base_name}-products-{environment}",
46-
"arn": f"arn:aws:dynamodb:{self.REGION}:*:table/{base_name}-products-{environment}",
47-
},
30+
"name": f"{base_name}-{environment}",
31+
"arn": f"arn:aws:dynamodb:{self.REGION}:*:table/{base_name}-{environment}"
4832
}
49-
50-
def get_table_name(self, entity: str) -> str:
51-
"""
52-
Retorna o nome da tabela para uma entidade específica.
53-
54-
Args:
55-
entity: Nome da entidade (certificates, orders, participants, products)
56-
57-
Returns:
58-
str: Nome da tabela no DynamoDB
59-
"""
60-
tables = self.dynamodb_tables
61-
if entity not in tables:
62-
raise ValueError(
63-
f"Entidade '{entity}' não encontrada. Entidades disponíveis: {list(tables.keys())}"
64-
)
65-
66-
return tables[entity]["name"]
67-
68-
def get_table_arn(self, entity: str) -> str:
69-
"""
70-
Retorna o ARN da tabela para uma entidade específica.
71-
72-
Args:
73-
entity: Nome da entidade (certificates, orders, participants, products)
74-
75-
Returns:
76-
str: ARN da tabela no DynamoDB
77-
"""
78-
tables = self.dynamodb_tables
79-
if entity not in tables:
80-
raise ValueError(
81-
f"Entidade '{entity}' não encontrada. Entidades disponíveis: {list(tables.keys())}"
82-
)
83-
84-
return tables[entity]["arn"]
33+
34+
@property
35+
def dynamodb_tables(self) -> Dict[str, Dict[str, str]]:
36+
return {"single": self.dynamodb_table}
37+
38+
def get_table_name(self, entity: str = None) -> str:
39+
return self.dynamodb_table["name"]
40+
41+
def get_table_arn(self, entity: str = None) -> str:
42+
return self.dynamodb_table["arn"]
8543

8644

8745
config = Config()
46+

0 commit comments

Comments
 (0)