# ju-lio/porteiro-game-erp architecture

> Architecture diagram of the GitHub repository ju-lio/porteiro-game-erp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ju-lio/porteiro-game-erp
- Repository: https://github.com/ju-lio/porteiro-game-erp

## Overview

#### Purpose and Runtime
Porteiro is a Next.js ERP for authoring game content. Editors manage draft content in Supabase Postgres/Storage; the game consumes only an immutable published JSON bundle via a public API. The application shell and route structure start at `src/app/layout.tsx`, `src/app/page.tsx`, and Next middleware in `src/middleware.ts`.

#### Access Boundary
Authentication is email/password through Supabase, with no self-registration. Middleware protects ERP routes; the game-content endpoint is deliberately public. Server-side Supabase access and auth actions are centralized in `src/lib/supabase.ts`, `src/lib/auth.ts`, and `src/lib/acoes-auth.ts`. RLS has no client policies, making the server/service-key boundary material.

#### Content Authoring Surface
Each `src/app/*` route is an editorial domain: world data, characters, gameplay definitions, and publishing. Simple entities use the reusable CRUD/form system in `src/componentes/Crud.tsx` and `src/componentes/campos.tsx`; richer domains provide dedicated screens, such as `src/app/personagens/pecas/Tela.tsx`, `src/app/mundo/regioes/Tela.tsx`, and `src/app/gameplay/regras/Tela.tsx`.

#### Character Art Pipeline
Character assembly is configured through palettes, ordered layers, and uploaded pieces. Uploads are validated against configured canvas dimensions, content-addressed by SHA-256, and stored immutably so historical bundles retain exact art references. Core boundaries are `src/componentes/Upload.tsx`, `src/componentes/PreviewPersonagem.tsx`, and `src/lib/imagem.ts`; authoring routes include `src/app/personagens/paletas/Tela.tsx` and `src/app/personagens/camadas/Tela.tsx`.

#### Game-Definition Model
The ERP expresses game behavior as data rather than game-side code: regions select required documents; documents define visible fields and authentic seal color; professions, items, marks, rules, posters, profiles, and missions define generation and difficulty. Important specialized editors include `src/app/gameplay/documentos/Tela.tsx`, `src/app/gameplay/profissoes/Tela.tsx`, and `src/app/gameplay/regras/Tela.tsx`.

#### Validation and Publication
Draft content is not directly exposed to the game. Publication builds a snapshot, runs domain validation, and creates versioned immutable bundles; errors block publication while warnings remain advisory. This stage is centered on `src/lib/validacao.ts`, `src/lib/bundle.ts`, and `src/lib/publicacao.ts`, with operator UI at `src/app/publicar/Tela.tsx` and version management at `src/app/publicar/versoes/Tela.tsx`.

#### Delivery API and Persistence
`src/app/api/conteudo/route.ts` is the game’s single read boundary: it returns the current published bundle or a requested version, isolating the game from database schema and drafts. Supporting server APIs are `src/app/api/upload/route.ts`, `src/app/api/versoes/route.ts`, and `src/app/api/config/route.ts`. The durable data model, constraints, RLS setup, and storage-oriented schema live in `supabase/schema.sql`.

Main entry points: [`supabase/schema.sql`](https://github.com/ju-lio/porteiro-game-erp/blob/main/supabase/schema.sql) (Draft data and art storage), [`src/app/layout.tsx`](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/layout.tsx) (Next.js shell and routes), [`src/app/personagens/paletas/Tela.tsx`](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/personagens/paletas/Tela.tsx) (Character assembly), [`src/lib/publicacao.ts`](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/publicacao.ts) (Publication service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Application shell"]
  node_next_shell["Next.js shell and routes<br/>Next.js app<br/>[layout.tsx]"]
  node_middleware["Route protection<br/>Next middleware<br/>[middleware.ts]"]
  node_auth["Server auth boundary<br/>Supabase auth<br/>[supabase.ts]"]
end

subgraph group_authoring["Editorial authoring"]
  node_crud["Reusable CRUD forms<br/>editor components<br/>[Crud.tsx]"]
  node_world_editor["World and regions<br/>editor route<br/>[Tela.tsx]"]
  node_character_editor["Character assembly<br/>editor routes<br/>[Tela.tsx]"]
  node_art_upload["Immutable art upload<br/>upload component<br/>[Upload.tsx]"]
  node_character_preview["Character preview<br/>preview component"]
  node_gameplay_editors["Game-definition editors<br/>editor routes<br/>[Tela.tsx]"]
  node_supabase[("Draft data and art storage<br/>Supabase Postgres/Storage<br/>[schema.sql]")]
end

subgraph group_publishing["Publication pipeline"]
  node_publish_ui["Publish and versions UI<br/>operator routes<br/>[Tela.tsx]"]
  node_validation["Domain validation<br/>validation service<br/>[validacao.ts]"]
  node_bundle_builder["Snapshot bundle builder<br/>bundle service<br/>[bundle.ts]"]
  node_publication["Publication service<br/>[publicacao.ts]"]
end

subgraph group_delivery["Game delivery"]
  node_content_api["Published content API<br/>public API route<br/>[route.ts]"]
  node_game(("Game client<br/>external consumer"))
end

node_next_shell -->|"routes pass through"| node_middleware
node_middleware -->|"checks session"| node_auth
node_next_shell -->|"renders simple editors"| node_crud
node_next_shell -->|"serves route"| node_world_editor
node_next_shell -->|"serves route"| node_character_editor
node_next_shell -->|"serves route"| node_gameplay_editors
node_crud -->|"reads and writes drafts"| node_supabase
node_world_editor -->|"writes draft world data"| node_supabase
node_character_editor -->|"uploads pieces"| node_art_upload
node_art_upload -->|"stores immutable assets"| node_supabase
node_character_editor -->|"previews layer assembly"| node_character_preview
node_gameplay_editors -->|"writes game definitions"| node_supabase
node_publish_ui -->|"requests publication"| node_publication
node_publication -->|"validates snapshot"| node_validation
node_validation -->|"valid drafts proceed"| node_bundle_builder
node_bundle_builder -->|"reads drafts and stores versions"| node_supabase
node_publication -->|"marks current version"| node_supabase
node_content_api -->|"reads published bundles"| node_supabase
node_game -->|"fetches current or versioned bundle"| node_content_api

click node_next_shell "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/layout.tsx"
click node_middleware "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/middleware.ts"
click node_auth "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/supabase.ts"
click node_crud "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/componentes/Crud.tsx"
click node_world_editor "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/mundo/regioes/Tela.tsx"
click node_character_editor "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/personagens/paletas/Tela.tsx"
click node_art_upload "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/componentes/Upload.tsx"
click node_character_preview "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/componentes/PreviewPersonagem.tsx"
click node_gameplay_editors "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/gameplay/documentos/Tela.tsx"
click node_supabase "https://github.com/ju-lio/porteiro-game-erp/blob/main/supabase/schema.sql"
click node_publish_ui "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/publicar/Tela.tsx"
click node_validation "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/validacao.ts"
click node_bundle_builder "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/bundle.ts"
click node_publication "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/publicacao.ts"
click node_content_api "https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/api/conteudo/route.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_next_shell,node_middleware,node_auth toneBlue
class node_crud,node_world_editor,node_character_editor,node_art_upload,node_character_preview,node_gameplay_editors,node_supabase toneAmber
class node_publish_ui,node_validation,node_bundle_builder,node_publication toneMint
class node_content_api,node_game toneRose
```

## Components

### Application shell

- [Next.js shell and routes](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/layout.tsx): Next.js app · ERP entry points and route structure. · `src/app/layout.tsx`
- [Route protection](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/middleware.ts): Next middleware · Protects ERP routes while leaving content delivery public. · `src/middleware.ts`
- [Server auth boundary](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/supabase.ts): Supabase auth · Centralizes server Supabase access and auth actions. · `src/lib/supabase.ts`

### Editorial authoring

- [Reusable CRUD forms](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/componentes/Crud.tsx): editor components · Shared forms for simple editorial entities. · `src/componentes/Crud.tsx`
- [World and regions](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/mundo/regioes/Tela.tsx): editor route · Authors world data and region requirements. · `src/app/mundo/regioes/Tela.tsx`
- [Character assembly](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/personagens/paletas/Tela.tsx): editor routes · Authors palettes, layers, and character pieces. · `src/app/personagens/paletas/Tela.tsx`
- [Immutable art upload](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/componentes/Upload.tsx): upload component · Validates dimensions and content-addresses uploaded pieces. · `src/componentes/Upload.tsx`
- [Character preview](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/componentes/PreviewPersonagem.tsx): preview component · `src/componentes/PreviewPersonagem.tsx`
- [Game-definition editors](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/gameplay/documentos/Tela.tsx): editor routes · Defines documents, professions, rules, and game data. · `src/app/gameplay/documentos/Tela.tsx`
- [Draft data and art storage](https://github.com/ju-lio/porteiro-game-erp/blob/main/supabase/schema.sql): Supabase Postgres/Storage · Holds editable content, immutable assets, constraints, and RLS. · `supabase/schema.sql`

### Publication pipeline

- [Publish and versions UI](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/publicar/Tela.tsx): operator routes · Operators publish drafts and manage bundle versions. · `src/app/publicar/Tela.tsx`
- [Domain validation](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/validacao.ts): validation service · Blocks publication errors and reports advisory warnings. · `src/lib/validacao.ts`
- [Snapshot bundle builder](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/bundle.ts): bundle service · Creates versioned immutable JSON snapshots. · `src/lib/bundle.ts`
- [Publication service](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/lib/publicacao.ts): publication service · Orchestrates validation and current-version publication. · `src/lib/publicacao.ts`

### Game delivery

- [Published content API](https://github.com/ju-lio/porteiro-game-erp/blob/main/src/app/api/conteudo/route.ts): public API route · Returns the current or requested immutable bundle only. · `src/app/api/conteudo/route.ts`
- **Game client**: external consumer · Consumes published JSON without access to drafts or schema.

## Connections

- Next.js shell and routes → Route protection: routes pass through
- Route protection → Server auth boundary: checks session
- Next.js shell and routes → Reusable CRUD forms: renders simple editors
- Next.js shell and routes → World and regions: serves route
- Next.js shell and routes → Character assembly: serves route
- Next.js shell and routes → Game-definition editors: serves route
- Reusable CRUD forms → Draft data and art storage: reads and writes drafts
- World and regions → Draft data and art storage: writes draft world data
- Character assembly → Immutable art upload: uploads pieces
- Immutable art upload → Draft data and art storage: stores immutable assets
- Character assembly → Character preview: previews layer assembly
- Game-definition editors → Draft data and art storage: writes game definitions
- Publish and versions UI → Publication service: requests publication
- Publication service → Domain validation: validates snapshot
- Domain validation → Snapshot bundle builder: valid drafts proceed
- Snapshot bundle builder → Draft data and art storage: reads drafts and stores versions
- Publication service → Draft data and art storage: marks current version
- Published content API → Draft data and art storage: reads published bundles
- Game client → Published content API: fetches current or versioned bundle