🎨 Diagrama Visual: Padrão Arquitetural
Data: 26 de fevereiro de 2026
Status: Validado em Locations + Testing Center
📊 Visão Geral: Hierarquia de Componentes
┌─────────────────────────────────────────────────────────────────┐
│ BROWSER WINDOW │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ AdminLayout (Global) │ │
│ │ ┌──────────┐ ┌──────────────────────────────────────┐ │ │
│ │ │ Sidebar │ │ Page Content │ │ │
│ │ │ (Global) │ │ │ │ │
│ │ │ │ │ ┌─────────────────────────────────┐ │ │ │
│ │ │ • Home │ │ │ AdminSectionLayout │ │ │ │
│ │ │ • Locais │ │ │ (Feature-Specific Wrapper) │ │ │ │
│ │ │ • Staff │ │ │ │ │ │ │
│ │ │ • Tests │ │ │ ┌─────────┐ ┌────────────┐ │ │ │ │
│ │ └──────────┘ │ │ │ │ │ Sidebar │ │ │ │ │
│ │ │ │ │ Content │ │ (Right) │ │ │ │ │
│ │ │ │ │ Area │ │ │ │ │ │ │
│ │ │ │ │ │ │ ┌────────┐ │ │ │ │ │
│ │ │ │ │ (Tabs │ │ │ 📋 List│ │ │ │ │ │
│ │ │ │ │ render │ │ ├────────┤ │ │ │ │ │
│ │ │ │ │ here) │ │ │ ➕ New │ │ │ │ │ │
│ │ │ │ │ │ │ ├────────┤ │ │ │ │ │
│ │ │ │ │ │ │ │ 📊 Stat│ │ │ │ │ │
│ │ │ │ └─────────┘ │ └────────┘ │ │ │ │ │
│ │ │ │ └────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────┘ │ │ │
│ │ └──────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
🔄 Fluxo de Dados: State Management
┌─────────────────────────────────────────────────────────────────┐
│ {Feature}Page.tsx │
│ (ORQUESTRADOR) │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ STATE │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ const [items, setItems] = useState([]) │ │ │
│ │ │ const [selectedItem, setSelectedItem] = useState(null)│ │ │
│ │ │ const [activeRightId, setActiveRightId] = useState() │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ HANDLERS │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ handleRightMenuSelect(id) → setActiveRightId(id) │ │ │
│ │ │ handleCreate(data) → API call → setItems([new, ...]) │ │ │
│ │ │ handleDelete(id) → API call → setItems(filtered) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ EFFECTS │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ useEffect(() => { │ │ │
│ │ │ api.list().then(setItems) │ │ │
│ │ │ }, []) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ RENDER │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ <AdminSectionLayout │ │ │
│ │ │ rightMenu={rightMenu} │ │ │
│ │ │ activeRightId={activeRightId} │ │ │
│ │ │ onRightSelect={handleRightMenuSelect} │ │ │
│ │ │ > │ │ │
│ │ │ {activeRightId === 'list' && <ListTab items={...}/>}│ │
│ │ │ {activeRightId === 'new' && <FormTab onSubmit={...}/>}│ │
│ │ │ </AdminSectionLayout> │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│ ▲
│ props down │ callbacks up
▼ │
┌─────────────────────────────────────────────────────────────────┐
│ AdminSectionLayout.tsx │
│ (APRESENTAÇÃO) │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ PROPS RECEBIDAS │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ title, rightMenu[], activeRightId, onRightSelect │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ RENDER GRID │ │
│ │ ┌────────────────────────┬─────────────────────────────┐ │ │
│ │ │ Content (children) │ Sidebar (rightMenu) │ │ │
│ │ │ │ │ │ │
│ │ │ {children} │ {rightMenu.map(item => ( │ │ │
│ │ │ ↑ │ <button │ │ │
│ │ │ │ │ onClick={() => │ │ │
│ │ │ Tabs renderizam aqui │ onRightSelect(item.id)│ │
│ │ │ │ } │ │ │
│ │ │ │ className={ │ │ │
│ │ │ │ activeRightId === id │ │ │
│ │ │ │ ? 'active' : '' │ │ │
│ │ │ │ } │ │ │
│ │ │ │ /> │ │ │
│ │ │ │ ))} │ │ │
│ │ └────────────────────────┴─────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│ ▲
│ render │ events
▼ │
┌─────────────────────────────────────────────────────────────────┐
│ Tab Components │
│ (COMPORTAMENTO) │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ ListTab.tsx │ │ FormTab.tsx │ │
│ │ ┌────────────────┐ │ │ ┌────────────────┐ │ │
│ │ │ PROPS │ │ │ │ PROPS │ │ │
│ │ │ items[] │ │ │ │ onSubmit() │ │ │
│ │ │ onDelete() │ │ │ │ onCancel() │ │ │
│ │ └────────────────┘ │ │ └────────────────┘ │ │
│ │ │ │ │ │
│ │ RENDER │ │ RENDER │ │
│ │ ┌────────────────┐ │ │ ┌────────────────┐ │ │
│ │ │ {items.map()} │ │ │ │ <form> │ │ │
│ │ │ <Card> │ │ │ │ <input> │ │ │
│ │ │ {item} │ │ │ │ <button │ │ │
│ │ │ <button │ │ │ │ onClick={ │ │ │
│ │ │ onClick={│ │ │ │ onSubmit} │ │ │
│ │ │ onDelete}│ │ │ │ /> │ │ │
│ │ │ /> │ │ │ │ </form> │ │ │
│ │ │ </Card> │ │ │ └────────────────┘ │ │
│ │ │ )}} │ │ │ │ │
│ │ └────────────────┘ │ │ │ │
│ └──────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
🎯 Fluxo de Interação: User Click → State Update → Re-render
┌─────────────────────────────────────────────────────────────────┐
│ STEP 1: User clicks sidebar button "➕ New" │
│ │
│ ┌────────────────────────────────────┐ │
│ │ AdminSectionLayout │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ <button │ │ │
│ │ │ onClick={() => │ │ │
│ │ │ onRightSelect('new') ◄──┼──┼─── USER CLICK │
│ │ │ } │ │ │
│ │ │ /> │ │ │
│ │ └──────────────────────────────┘ │ │
│ └────────────────────────────────────┘ │
│ │ │
│ │ callback invoked │
│ ▼ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ STEP 2: Handler updates state │
│ │
│ ┌────────────────────────────────────┐ │
│ │ {Feature}Page │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ function handleRightMenuSelect│ │ │
│ │ │ (id: string) { │ │ │
│ │ │ setActiveRightId(id) ◄─────┼──┼─── CALLED │
│ │ │ } │ │ with 'new' │
│ │ └──────────────────────────────┘ │ │
│ └────────────────────────────────────┘ │
│ │ │
│ │ state updated │
│ ▼ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ STEP 3: React re-renders component │
│ │
│ ┌────────────────────────────────────┐ │
│ │ {Feature}Page │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ const activeRightId = 'new' │ │ ◄── STATE NOW │
│ │ └──────────────────────────────┘ │ 'new' │
│ │ │ │
│ │ CONDITIONAL EVALUATION: │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ {activeRightId === 'list' && │ │ ◄── FALSE ❌ │
│ │ │ <ListTab />} │ │ (skipped) │
│ │ │ │ │ │
│ │ │ {activeRightId === 'new' && │ │ ◄── TRUE ✅ │
│ │ │ <FormTab />} │ │ (renders) │
│ │ └──────────────────────────────┘ │ │
│ └────────────────────────────────────┘ │
│ │ │
│ │ FormTab rendered │
│ ▼ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ STEP 4: UI updates (user sees FormTab) │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Browser renders FormTab │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ <form> │ │ │
│ │ │ <input name="name" /> │ │ │
│ │ │ <input name="description" │ │ │
│ │ │ <button>Salvar</button> │ │ │
│ │ │ <button>Cancelar</button> │ │ │
│ │ │ </form> │ │ │
│ │ └──────────────────────────────┘ │ │
│ └────────────────────────────────────┘ │
│ │
│ Sidebar button "➕ New" now has active styling (green border) │
└─────────────────────────────────────────────────────────────────┘
🏗️ Arquitetura Backend: API → Database
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ {feature}Api.create(data) │ │
│ │ → axios.post('/api/{feature}', data) │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
│ HTTP POST /api/{feature}
│ { name: "Test", ... }
▼
┌─────────────────────────────────────────────────────────────────┐
│ BACKEND - FastAPI │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ routes.py │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ @router.post("/") │ │ │
│ │ │ async def create_item( │ │ │
│ │ │ data: CreateItemDto, ◄──────────────────────────┼──┼── Pydantic
│ │ │ db: Session = Depends(get_db) │ │ validation
│ │ │ ): │ │ │
│ │ │ service = MyFeatureService(db) │ │ │
│ │ │ return service.create(data) │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ │ calls service │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ service.py │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ class MyFeatureService: │ │ │
│ │ │ def create(self, data: CreateItemDto): │ │ │
│ │ │ item = MyFeatureItem(**data.dict()) │ │ │
│ │ │ self.db.add(item) ◄────────────────────────────┼──┼── SQLAlchemy
│ │ │ self.db.commit() │ │ ORM
│ │ │ self.db.refresh(item) │ │ │
│ │ │ return item │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
│ SQL INSERT INTO
▼
┌─────────────────────────────────────────────────────────────────┐
│ DATABASE - PostgreSQL │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ {feature}_items table │ │
│ │ ┌────┬────────┬──────────────┬────────────┬───────────┐ │ │
│ │ │ id │ name │ description │ status │ created_at│ │ │
│ │ ├────┼────────┼──────────────┼────────────┼───────────┤ │ │
│ │ │ 1 │ Test │ Lorem ipsum │ active │ 2026-... │ │ ◄─ NEW ROW
│ │ └────┴────────┴──────────────┴────────────┴───────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
│ return ItemResponse
▼
┌─────────────────────────────────────────────────────────────────┐
│ BACKEND RESPONSE │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ HTTP 201 Created │ │
│ │ { id: 1, name: "Test", status: "active", ... } │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
│ axios resolves promise
▼
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ const newItem = await api.create(data) │ │
│ │ setItems(prev => [newItem, ...prev]) ◄──────────────────┼── State
│ │ setActiveRightId('list') │ │ updated
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
│ React re-renders
▼
┌─────────────────────────────────────────────────────────────────┐
│ UI UPDATES │
│ - FormTab unmounts │
│ - ListTab renders │
│ - New item appears at top of list │
│ - Success toast: "Item criado com sucesso" │
└─────────────────────────────────────────────────────────────────┘
📦 Estrutura de Módulos: Dependências
┌─────────────────────────────────────────────────────────────────┐
│ PROJECT ROOT │
└─────────────────────────────────────────────────────────────────┘
│ │
│ │
┌──────┴────────┐ ┌─────┴──────┐
│ FRONTEND │ │ BACKEND │
└───────────────┘ └────────────┘
│ │
┌──────┴────────────────┐ ┌──────┴──────────────┐
│ │ │ │ │ │ │ │
┌───▼──┐ ┌─▼───┐ ┌──▼──┐ ┌─▼──┐ ┌──▼───┐ ┌─▼───┐ ┌─▼───┐ ┌──▼──┐
│pages │ │comp.│ │serv.│ │types│ │routes│ │models│ │schm.│ │serv.│
└──────┘ └─────┘ └─────┘ └─────┘ └──────┘ └──────┘ └─────┘ └─────┘
│ │ │ │ │ │ │
▼ ▼ │ ▼ ▼ ▼ │
│ │ │ │ │ │ │
└────────┴───────┼───────────────────┘ │ │ │
│ │ │ │
│ │ │ │
└────────────────────────────┴───────┴───────┘
│
▼
┌───────────────┐
│ DATABASE │
│ (PostgreSQL) │
└───────────────┘
LEGENDA:
pages → Page Components (orquestradores)
comp. → Tab Components (puros)
serv. → API Clients (axios)
types → TypeScript interfaces
routes → FastAPI endpoints
models → SQLAlchemy models
schm. → Pydantic schemas
serv. → Business logic services
Regras de dependência:
- ✅ pages → components (pode importar)
- ✅ pages → services (pode importar)
- ✅ pages → types (pode importar)
- ❌ components → pages (NUNCA importar)
- ❌ components → services (NUNCA - recebe via props)
- ✅ routes → service (pode importar)
- ✅ service → models (pode importar)
- ✅ routes → schemas (pode importar)
- ❌ models → service (NUNCA - circular)
🎨 Layout Responsivo: Grid System
Desktop (≥1280px)
┌──────────────────────────────────────────────────────────────┐
│ Header │
├────────────────────────────────────────────┬─────────────────┤
│ │ │
│ Content Area │ Sidebar │
│ (Tabs render) │ (320px) │
│ │ │
│ [1fr] │ [320px] │
│ │ │
│ {activeRightId === 'list' && <ListTab/>} │ ┌───────────┐ │
│ │ │ 📋 List │ │
│ │ ├───────────┤ │
│ │ │ ➕ New │ │
│ │ ├───────────┤ │
│ │ │ 📊 Stats │ │
│ │ └───────────┘ │
└────────────────────────────────────────────┴─────────────────┘
Grid: xl:grid-cols-[1fr_320px]
Gap: gap-6 (24px)
Tablet (768px - 1279px)
┌──────────────────────────────────────────────────────────────┐
│ Header │
├────────────────────────────────────────────┬─────────────────┤
│ │ │
│ Content Area │ Sidebar │
│ (Tabs render) │ (280px) │
│ │ │
│ [1fr] │ [280px] │
│ │ │
│ │ Buttons │
│ │ stacked │
│ │ │
└────────────────────────────────────────────┴─────────────────┘
Grid: md:grid-cols-[1fr_280px]
Mobile (<768px)
┌──────────────────────────────────┐
│ Header │
├──────────────────────────────────┤
│ Sidebar (Full Width) │
│ ┌────┬────┬────┬────────────┐ │
│ │📋 │➕ │📊 │⚙️ │ │ ← Horizontal scroll
│ │List│New │Stat│Settings │ │
│ └────┴────┴────┴────────────┘ │
├──────────────────────────────────┤
│ │
│ Content Area │
│ (Full Width) │
│ │
│ {activeRightId === 'list' && │
│ <ListTab />} │
│ │
│ │
└──────────────────────────────────┘
Grid: grid-cols-1
Sidebar: Horizontal scrollable buttons strip
🚦 Estado do Botão: Visual Feedback
Botão Inativo (default)
┌─────────────────────────────────┐
│ 📋 Listar │ ← bg-slate-800/30
│ │ border-slate-700/30
└─────────────────────────────────┘ text-slate-400
Botão Hover (mouse over)
┌─────────────────────────────────┐
│ 📋 Listar │ ← bg-slate-800/50 (lighter)
│ │ cursor-pointer
└─────────────────────────────────┘ transition smooth
Botão Ativo (selected)
┌─────────────────────────────────┐
│ 📋 Listar │ ← bg-blue-500/20
│ │ border-blue-500/50
└─────────────────────────────────┘ text-blue-400
▲ glow effect
└── activeRightId === 'list'
Código:
className={`
w-full flex items-center gap-3 px-4 py-3 rounded-lg
transition-all duration-200 border
${activeRightId === item.id
? `bg-${item.color}-500/20 border-${item.color}-500/50 text-${item.color}-400`
: 'bg-slate-800/30 border-slate-700/30 text-slate-400 hover:bg-slate-800/50'
}
`}
🔄 Ciclo de Vida Completo: Create → List
T0: User está em ListTab
┌────────────────────────────────┐
│ activeRightId = 'list' │
│ items = [existing items...] │
└────────────────────────────────┘
T1: User clica "➕ New"
┌────────────────────────────────┐
│ onRightSelect('new') called │
│ → handleRightMenuSelect('new') │
│ → setActiveRightId('new') │
└────────────────────────────────┘
T2: React re-renders
┌────────────────────────────────┐
│ activeRightId = 'new' │
│ FormTab renders │
│ ListTab unmounts │
└────────────────────────────────┘
T3: User fills form & submits
┌────────────────────────────────┐
│ onSubmit(data) called │
│ → handleCreate(data) │
│ → api.create(data) │
└────────────────────────────────┘
T4: API call in progress
┌────────────────────────────────┐
│ setLoading(true) │
│ Button disabled │
│ Spinner shows │
└────────────────────────────────┘
T5: API responds 201
┌────────────────────────────────┐
│ const newItem = response.data │
│ setItems([newItem, ...prev]) │
│ setActiveRightId('list') │
│ setLoading(false) │
└────────────────────────────────┘
T6: React re-renders
┌────────────────────────────────┐
│ activeRightId = 'list' │
│ items = [newItem, ...existing] │
│ ListTab renders │
│ FormTab unmounts │
│ Toast: "Criado com sucesso" │
└────────────────────────────────┘
T7: User sees updated list
┌────────────────────────────────┐
│ New item appears at top │
│ Success feedback visible │
│ "➕ New" button inactive │
│ "📋 List" button active │
└────────────────────────────────┘
🎯 Este diagrama deve ser referência visual ao implementar novas features.
Para código detalhado e templates, consultar: