Praxis Metadata Starter - Visao Arquitetural

A arquitetura atual do praxis-metadata-starter nao deve mais ser explicada como “DTO anotado gera CRUD”. O baseline canonico evoluiu para um sistema resource-oriented que publica:

OpenAPI enriquecido com x-ui
/schemas/filtered como contrato estrutural
/schemas/catalog como catalogo documental
/schemas/surfaces e /schemas/actions como discovery semantico
/{resource}/capabilities e /{resource}/{id}/capabilities como snapshot agregado
RestApiResponse com Spring HATEOAS efetivo

1. O Que E Canonicamente Publicado

flowchart LR
    host["Spring Boot host"] --> auto["PraxisMetadataAutoConfiguration"]
    auto --> openapi["OpenAPI enriched with x-ui"]
    openapi --> filtered["/schemas/filtered"]
    openapi --> catalog["/schemas/catalog"]
    openapi --> surfaces["/schemas/surfaces"]
    openapi --> actions["/schemas/actions"]
    surfaces --> caps["/{resource}/capabilities"]
    actions --> caps
    filtered --> runtime["praxis-ui-angular runtime"]
    catalog --> docs["docs, examples, RAG"]
    caps --> semantic["semantic clients and assistants"]

O contrato estrutural e o discovery semantico tem papeis diferentes:

/schemas/filtered e a superficie lida pelo runtime para renderizacao
/schemas/catalog organiza exemplos, links e sumarios para exploracao
/schemas/surfaces e /schemas/actions publicam catalogos semanticos
/{resource}/capabilities agrega o que pode ser feito agora sem virar um schema alternativo

2. Baseline De Modelagem

Para aplicacoes novas, o baseline correto e:

AbstractResourceController
AbstractReadOnlyResourceController
AbstractBaseResourceService
AbstractReadOnlyResourceService
ResourceMapper
@ApiResource(value = ..., resourceKey = ...)

O modelo esperado separa:

ResponseDTO
CreateDTO
UpdateDTO
FilterDTO

@UISchema continua relevante para metadados de campo, mas ele ja nao descreve sozinho a arquitetura publica do starter.

3. Camadas Principais

Auto-configuracao

PraxisMetadataAutoConfiguration
OpenApiUiSchemaAutoConfiguration
DynamicSwaggerConfig

Essas pecas registram controllers, resolvers, grouped OpenAPI e o suporte de docs/discovery.

Resolucao de contrato

CustomOpenApiResolver
OpenApiGroupResolver
OpenApiDocsSupport

Aqui o starter transforma DTOs, Bean Validation e metadata de recurso em OpenAPI enriquecido e grupos canonicamente resolvidos por path.

Publicacao de docs e discovery

ApiDocsController
DomainCatalogController
SurfaceCatalogController
ActionCatalogController

Esses controllers nao sao equivalentes entre si:

ApiDocsController publica o payload estrutural
DomainCatalogController publica o catalogo documental
SurfaceCatalogController publica surfaces canonicas do recurso
ActionCatalogController publica workflow actions canonicamente anotadas

Semantica de recurso

@ApiResource
@ResourceIntent
@UiSurface
@WorkflowAction
resolvers de capability

Aqui a arquitetura sai do antigo “CRUD com metadata” e passa para semantica de recurso, experiencia e acao de negocio.

4. Fluxo Estrutural

sequenceDiagram
    participant DTO as DTOs + validation
    participant Resolver as CustomOpenApiResolver
    participant OpenAPI as OpenAPI document
    participant Docs as ApiDocsController
    participant Runtime as Angular runtime

    DTO->>Resolver: field metadata, validation, resource semantics
    Resolver->>OpenAPI: persist x-ui and operation metadata
    Docs->>OpenAPI: resolve best group for the requested path
    Docs->>Docs: filter request or response schema
    Docs->>Docs: inject x-ui.resource and cache headers
    Docs-->>Runtime: structural payload for rendering

Esse fluxo ainda e o centro do runtime oficial.

O que mudou foi a semantica ao redor dele:

x-ui.resource.capabilities nao e mais o unico discovery relevante
a plataforma agora diferencia contrato estrutural de catalogos semanticos
item-level discovery e agregado contextual ganharam papel de primeira classe

5. Fluxo Semantico

sequenceDiagram
    participant Resource as @ApiResource
    participant Surface as @UiSurface
    participant Action as @WorkflowAction
    participant Catalogs as surface/action catalogs
    participant Capabilities as capability resolver
    participant Client as semantic client

    Resource->>Catalogs: publish automatic resource surfaces
    Surface->>Catalogs: publish explicit UX surfaces
    Action->>Catalogs: publish explicit workflow actions
    Catalogs->>Capabilities: contribute semantic entries
    Capabilities-->>Client: aggregate current snapshot

Regras importantes:

surfaces automaticas continuam existindo para o recurso canonico
actions dependem de workflow explicito; ausencia pode resultar em 404
capabilities agrega ausencia de surfaces e actions como listas vazias
entradas ITEM em catalogos globais sao discovery-only ate existir resourceId

6. Spring HATEOAS Faz Parte Da Arquitetura

HATEOAS nao e detalhe de serializacao.

Ele compoe a semantica publica em:

_links de RestApiResponse
links canonicamente montados pelos controllers base
navegacao entre recurso, schema e operacoes
coerencia entre contrato publicado e affordances HTTP

Quando o host desliga HATEOAS, a plataforma perde links, nao a semantica canonica de recurso e discovery.

7. Consumidores De Referencia

`praxis-api-quickstart`

E o host operacional de referencia. Ele prova:

resolucao de grupos OpenAPI por path
publicacao coerente de /schemas/catalog
publicacao coerente de /schemas/filtered
discovery resource-oriented
consistencia entre stats, resource semantics e examples

`praxis-ui-angular`

E o runtime oficial. Ele consome:

/schemas/filtered
ETag
X-Schema-Hash
x-ui.resource.idField

Ele pode tambem usar discovery semantico novo, mas o contrato estrutural segue sendo a base do runtime.

8. O Que Nao Deve Ser Repetido Na Documentacao Publica

Nao explicar o starter como se ele fosse:

apenas um gerador de CRUD
apenas @UISchema + AbstractCrudController
um sistema em que /schemas/catalog substitui /schemas/filtered
um backend que publica schema estrutural sem semantica de recurso

Essas leituras ficaram historicamente incompletas.