docs: update all documentation and add AI tooling configs

- Rewrite README.md with current architecture, features and stack
- Update docs/API.md with all current endpoints (corporate, BI, client 360)
- Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL
- Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente)
- Add docs/INDEX.md documentation index
- Add PROJETO.md comprehensive project reference
- Add BI-CCC-Implementation-Guide.md
- Include AI agent configs (.claude, .agents, .gemini, _bmad)
- Add netbird VPN configuration
- Add status report

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-03-19 13:29:03 -04:00
parent c5b377e788
commit 647cbec54f
3246 changed files with 479789 additions and 983 deletions

View File

@@ -0,0 +1,59 @@
# Design Log
**Project:** {{project_name}}
**Started:** {{date}}
**Method:** Whiteport Design Studio (WDS)
---
## Backlog
> Business-value items. Add links to detail files if needed.
- [ ] Complete product brief — Phase 1
- [ ] Define trigger map — Phase 2
- [ ] Create user scenarios — Phase 3
---
## Current
| Task | Started | Agent |
|------|---------|-------|
| — | — | — |
**Rules:** Mark what you start. Complete it when done (move to Log). One task at a time per agent.
---
## Design Loop Status
> Per-page design progress. Updated by agents at every design transition.
| Scenario | Step | Page | Status | Updated |
|----------|------|------|--------|---------|
**Status values:** `discussed``wireframed``specified``explored``building``built``approved` | `removed`
**How to use:**
- **Append a row** when a page reaches a new status (do not overwrite — latest row per page is current status)
- **Read on startup** to see where the project stands and what to suggest next
---
## Log
### {{date}} — Project initialized (Phase 0)
- Type: {{greenfield/brownfield}}
- Complexity: {{product_complexity}}
- Tech stack: {{tech_stack}}
---
## About This Folder
- **This file** — Single source of truth for project progress
- **agent-experiences/** — Compressed insights from design discussions (dated files)
- **wds-project-outline.yaml** — Project configuration from Phase 0 setup
**Do not modify `wds-project-outline.yaml`** — it is the source of truth for project configuration.

View File

@@ -0,0 +1,251 @@
# Design System: {{project_name}}
> Components, tokens, and patterns that grow from actual usage — not upfront planning.
**Created:** {{date}}
**Phase:** 7 — Design System (optional)
**Agent:** Freya (Designer)
---
## What Belongs Here
The Design System captures reusable patterns that emerge during UX Design (Phase 4). It is not designed upfront — it crystallizes from real page specifications.
**What goes here:**
- **Design Tokens** — Colors, spacing, typography, shadows
- **Components** — Buttons, inputs, cards, navigation elements
- **Patterns** — Layouts, form structures, content blocks
- **Visual Design** — Mood boards, design concepts, color and typography explorations
- **Assets** — Logos, icons, images, graphics
**What does NOT go here:**
- Page-specific content (that lives in `C-UX-Scenarios/`)
- Business logic or API specs (that's BMM territory)
- Aspirational components nobody uses yet
**When to skip this phase:**
- Using shadcn/ui or Material UI → the library IS your design system
- Simple sites with Tailwind → tokens in `tailwind.config` are enough
**Learn more:**
- WDS Course Module 12: Functional Components — Patterns Emerge
- WDS Course Module 13: Design System
---
## Folder Structure
```
D-Design-System/
├── 00-design-system.md ← This file (hub + guide)
├── 01-Visual-Design/ [Early design exploration]
│ ├── mood-boards/ [Visual inspiration, style exploration]
│ ├── design-concepts/ [NanoBanana outputs, design explorations]
│ ├── color-exploration/ [Color palette experiments]
│ └── typography-tests/ [Font pairing and hierarchy tests]
├── 02-Assets/ [Final production assets]
│ ├── logos/ [Brand logos and variations]
│ ├── icons/ [Icon sets]
│ ├── images/ [Photography, illustrations]
│ └── graphics/ [Custom graphics and elements]
└── components/ [Emerges during Phase 4]
├── interactive/ [Buttons, toggles, tabs]
├── form/ [Inputs, selects, checkboxes]
├── layout/ [Containers, grids, sections]
├── content/ [Cards, lists, media blocks]
├── feedback/ [Alerts, toasts, progress]
└── navigation/ [Menus, breadcrumbs, links]
```
**01-Visual-Design/** is used early — before or during scenarios — for exploring visual direction. Mood boards, color palettes, typography tests, and AI-generated design concepts live here.
**02-Assets/** holds final, production-ready assets. Logos, icons, images, and graphics that are referenced from page specifications.
**components/** grows organically during Phase 4 as patterns emerge across page specifications.
---
## For Agents
**Workflow:** `_bmad/wds/workflows/7-design-system/workflow.md`
**Agent trigger:** `DS` (Freya)
**Router:** `_bmad/wds/workflows/7-design-system/design-system-router.md`
**Templates:** `_bmad/wds/workflows/7-design-system/templates/`
**Guide:** `_bmad/wds/data/agent-guides/freya/design-system.md`
**Before creating any component:**
1. Check if it already exists in the chosen component library
2. Look at actual usage in `C-UX-Scenarios/` page specs — extract, don't invent
3. Load the component template from the workflow templates folder
**File naming:** Number all documents with a two-digit prefix: `01-design-tokens.md`, `02-button.md`, etc. Update the sections below as each file is created.
**Harm:** Designing an abstract component library before any pages exist. Components without real usage are decoration. They waste time and create maintenance burden for patterns nobody needs.
**Help:** Extracting patterns from real page specs. When three pages use similar card layouts, that's a component. The design system documents what emerged, making future pages faster and more consistent.
---
## Spacing Scale
> **Bring your own or use ours.** If your project already has a design system with a spacing scale (Tailwind, Material, Carbon, your own tokens), use that. Map your token names below so page specs reference them consistently. If you don't have one yet, WDS provides a default 9-token scale to get started.
### Option A: Use your existing design system
Replace the table below with your system's spacing tokens. Any naming convention works — numbered (`spacing-4`), t-shirt (`sm`/`md`/`lg`), or your own. The only rule: page specs reference token names, never raw pixel values.
### Option B: WDS default scale
Nine tokens, symmetric around `space-md` (the baseline). Freya will propose pixel values during the first design session.
`space-md` is to spacing what `text-md` is to typography — the default you reach for first. It's the gap between paragraphs, between form fields, between list items. Everything else is relative to it: `space-sm` is tighter, `space-lg` is more generous.
| Token | Value | Use |
|-------|-------|-----|
| space-3xs | — | Hairline gaps (icon-to-label, inline elements) |
| space-2xs | — | Minimal spacing (badge padding, tight lists) |
| space-xs | — | Tight spacing (within compact groups) |
| space-sm | — | Small gaps (between related elements) |
| **space-md** | — | **Default element spacing (the baseline)** |
| space-lg | — | Comfortable spacing (card padding, form fields) |
| space-xl | — | Section padding |
| space-2xl | — | Section gaps |
| space-3xl | — | Page-level breathing room |
### Optical adjustments
Sometimes the math is right but the eye says it's wrong. A circular image leaves white corners, a light element on a light background looks more spaced than it is. When this happens, use token math — not raw pixels:
```
space-lg - space-3xs → "standard spacing, pulled in by a hairline"
space-xl + space-2xs → "section padding, nudged out slightly"
```
In page specs, always annotate why:
| Padding top | **space-lg - space-3xs** (optical: circular image adds perceived whitespace) |
**Rules:**
- Adjustments always use token math: `base ± correction`
- Always annotate the reason — future readers need to know this wasn't a mistake
- If adjusting by more than one step, the base token is probably wrong — reconsider
In CSS: `calc(var(--space-lg) - var(--space-3xs))`
<!--
space-md is typically 16px (on an 8px grid) or 12px (on a 4px grid) — the most common
default spacing on the web. Same ballpark as body text size, which is not a coincidence.
The pixel values are yours to define. Common starting points:
2/4/8/12/16/24/32/48/64 (8px grid) or 4/6/12/16/24/32/48/72.
You can adjust later — specs stay valid because they reference names, not numbers.
-->
---
## Type Scale
> **Bring your own or use ours.** Same principle as spacing — if your project has a type system, map it here. If not, use the WDS default.
The type scale controls **visual size** — how big text looks. This is separate from semantic level (H1, H2, p) which controls **document structure**. An H2 in a sidebar might be `text-sm`. A tagline might be a `<p>` at `text-2xl`. The semantic level is for accessibility and SEO; the type token is for visual hierarchy.
Headings can have different typefaces, weights, and styles on different pages. A landing page H1 might be a serif display font at `text-3xl` italic. An admin page H1 might be clean sans-serif at `text-lg` medium. Each page spec declares its own typographic treatment — the type scale provides the shared sizing vocabulary.
### Option A: Use your existing type system
Replace the table below with your system's type tokens.
### Option B: WDS default scale
Nine tokens, symmetric around `text-md` (body text). Freya will propose sizes during the first design session.
| Token | Value | Use |
|-------|-------|-----|
| text-3xs | — | Fine print, legal text |
| text-2xs | — | Metadata, timestamps |
| text-xs | — | Captions, helper text |
| text-sm | — | Labels, secondary text |
| text-md | — | Body text (the baseline) |
| text-lg | — | Emphasis, lead paragraphs |
| text-xl | — | Subheadings |
| text-2xl | — | Section titles, display text |
| text-3xl | — | Hero headings, page titles |
<!--
text-md (body text) is typically 16px or 14px — the most common baseline on the web.
Common starting points: 11/12/13/14/16/18/20/24/32 or 10/11/12/14/16/18/22/30/40.
Line heights should align to your spacing grid for vertical rhythm.
-->
---
## Tokens
_Additional design tokens (colors, shadows, borders) will be documented here as they emerge from page specifications._
---
## Patterns
<!--
Patterns are organized BY the spacing, not by object pairs.
Each spacing value/composition accumulates a list of where it's used.
When the designer says "more space here", the agent fixes it, reflects
what it learned, and adds the situation to the relevant pattern below.
The agent does NOT ask "why?" — it observes and reflects:
"Got it — large image above a card row needs extra room. I'll remember that."
EXTRACTION RULES — objects vs spacing:
- Objects: first use stays in the page spec. Second use → extract here.
- Spacing: first use → immediately extract here. No waiting.
Spacing is relational — a decision about two object types is universal from day one.
CONTEXT RULE: Entries are context-free by default (universal).
Add context only when the same object pair needs DIFFERENT spacing
in different situations. When that happens, BOTH entries get context
so you can tell them apart. Before the first violation, keep it clean.
-->
Spacing objects are first-class — they have IDs in page specs (e.g., `hem-v-space-xl`) and live here organized by value. Each spacing value accumulates the situations where it's used. The list grows from real design decisions.
_Patterns will be documented here as spacing objects recur across pages._
<!--
Example format (delete when real patterns emerge):
### space-sm
| Above | Below | Why |
|-------|-------|-----|
| Heading | Subheading | Tight pair — always read together |
| Icon | Label (inside button) | Compact inline group |
### space-lg
| Above | Below | Why |
|-------|-------|-----|
| Card | Card (grid gap) | Comfortable breathing room |
| Image | Caption | Standard image-to-text |
### space-zero
| Above | Below | Why |
|-------|-------|-----|
| Header | Service menu | One continuous nav unit |
| Icon bar | Section below | Flush — belongs to the section above |
### v-separator-2xl
| Above | Below | Why |
|-------|-------|-----|
| About preview | Trust cards | Gray line, equal space above/below |
-->
---
## Components
_Components will be documented here as patterns emerge across scenarios._
---
_Created using Whiteport Design Studio (WDS) methodology_

View File

@@ -0,0 +1,59 @@
# Product Brief: {{project_name}}
> The strategic foundation — why this product exists, who it serves, and what success looks like.
**Created:** {{date}}
**Phase:** 1 — Product Brief
**Agent:** Saga (Analyst)
---
## What Belongs Here
The Product Brief answers five strategic questions:
1. **Why** does this product exist? (Vision & business goals)
2. **Who** is it for? (Target users and their context)
3. **What** does it need to do? (Core capabilities)
4. **How** will we know it works? (Success metrics)
5. **What** are the constraints? (Platform requirements, tech stack)
Everything downstream — trigger maps, scenarios, page specs, design system — traces back to decisions made here. This is the North Star.
**Learn more:**
- WDS Course Module 04: Product Brief — Your Strategic Foundation
- WDS Course Module 05: Platform Requirements
---
## For Agents
**Workflow:** `_bmad/wds/workflows/1-project-brief/workflow.md`
**Agent trigger:** `PB` (Saga)
**Templates:** `_bmad/wds/workflows/1-project-brief/templates/`
**Before writing anything in this folder:**
1. Load the workflow and follow its steps
2. Use Dialog mode for discovery — ask questions, don't assume
3. Read existing materials if the user has them (check `wds-project-outline.yaml`)
**File naming:** Number all documents with a two-digit prefix: `01-product-brief.md`, `02-content-language.md`, etc. Platform Requirements is always last — it summarizes technical decisions that emerge from the strategic documents above. Update the Documents table below as each file is created.
**Harm:** Producing a brief from assumptions instead of conversation. A brief that doesn't reflect the user's actual goals forces every later phase to build on a wrong foundation.
**Help:** Asking the right questions, listening deeply, and documenting what the user actually said. A good brief makes every later decision easier.
---
## Documents
_This section will be updated as documents are created during Phase 1._
| # | Document | Status |
|---|----------|--------|
| 01 | Product Brief | Not started |
| 02 | Platform Requirements | Not started |
---
_Created using Whiteport Design Studio (WDS) methodology_

View File

@@ -0,0 +1,66 @@
# Trigger Map: {{project_name}}
> Connect business goals to user psychology — understand why people act, not just what they do.
**Created:** {{date}}
**Phase:** 2 — Trigger Mapping
**Agent:** Saga (Analyst)
---
## What Belongs Here
The Trigger Map reveals the human forces behind product decisions through five workshops:
1. **Business Goals** — What the business needs to achieve
2. **Target Groups** — Who the users are (with alliterative persona names)
3. **Driving Forces** — What motivates and frightens each persona (positive + negative)
4. **Prioritization** — Which forces matter most (scored by frequency, intensity, fit)
5. **Feature Impact** — How product features address the highest-priority forces
This folder feeds directly into Phase 4 (UX Scenarios). Every page spec should trace back to a driving force documented here.
**Learn more:**
- WDS Course Module 06: Trigger Mapping — Connect Business Goals to User Psychology
- WDS Course Module 06, Lessons 48: The Five Workshops
---
## For Agents
**Workflow:** `_bmad/wds/workflows/2-trigger-mapping/workflow.md`
**Agent trigger:** `TM` (Saga)
**Templates:** `_bmad/wds/workflows/2-trigger-mapping/templates/`
**Before writing anything in this folder:**
1. Read the Product Brief in `A-Product-Brief/` — trigger mapping builds on it
2. Load the workflow and follow the five workshop sequence
3. Use Dialog mode — personas emerge from conversation, not invention
**File naming:** Number all documents with a two-digit prefix: `01-business-goals.md`, `02-lars-the-loyal.md`, etc. One file per persona. Update the Documents table below as each file is created.
**Harm:** Inventing personas without discovery. Fabricated driving forces produce scenarios that solve imaginary problems. The user pays to correct work that should never have been written.
**Help:** Uncovering real psychology through conversation. When driving forces are authentic, every downstream design decision has a clear "why."
---
## Documents
_This section will be updated as documents are created during Phase 2._
| # | Document | Purpose | Status |
|---|----------|---------|--------|
| 01 | Business Goals | Vision, objectives, metrics | Not started |
| 02+ | Persona files | One per target group | Not started |
| — | Feature Impact Analysis | Forces × features scoring | Not started |
---
## Trigger Map Visualization
_A mermaid diagram connecting goals → platform → personas → forces will be added here during Phase 2._
---
_Created using Whiteport Design Studio (WDS) methodology_

View File

@@ -0,0 +1,85 @@
# UX Scenarios: {{project_name}}
> Design experiences, not screens — every page serves a user with a goal and an emotion.
**Created:** {{date}}
**Phase:** 3 (Scenario Outline) + Phase 4 (UX Design)
**Agents:** Saga (Scenario Outline), Freya (Page Specifications)
---
## What Belongs Here
Scenarios organize the product into meaningful user journeys. Each scenario groups related pages. Each page gets a full specification that a developer can build from.
**Folder structure per scenario:**
```
C-UX-Scenarios/
├── 00-ux-scenarios.md ← This file (scenario guide + page index)
├── 01-scenario-name/
│ ├── 1.1-page-name/
│ │ ├── 1.1-page-name.md ← Page specification
│ │ └── Sketches/ ← Wireframes and concepts
│ ├── 1.2-page-name/
│ │ ├── 1.2-page-name.md
│ │ └── Sketches/
│ └── ...
├── 02-scenario-name/
│ └── ...
├── Components/ ← Shared component specs
└── Features/
└── Storyboards/ ← Multi-step interaction flows
```
**Learn more:**
- WDS Course Module 08: Outline Scenarios — Design Experiences Not Screens
- WDS Course Module 09: Conceptual Sketching
- WDS Course Module 10: Storyboarding
- WDS Course Module 11: Conceptual Specifications
- WDS Course Tutorial 08: From Trigger Map to Scenarios
---
## For Agents
### Scenario Outline (Saga)
**Workflow:** `_bmad/wds/workflows/3-scenarios/workflow.md`
**Agent trigger:** `SC` (Saga)
### Page Specifications (Freya)
**Workflow:** `_bmad/wds/workflows/4-ux-design/workflow.md`
**Agent trigger:** `UX` (Freya)
**Page template:** `_bmad/wds/workflows/4-ux-design/templates/page-specification.template.md`
**Scenario template:** `_bmad/wds/workflows/4-ux-design/templates/scenario-overview.template.md`
**Quality guide:** `_bmad/wds/data/agent-guides/freya/specification-quality.md`
**Object types:** `_bmad/wds/workflows/4-ux-design/object-types/`
### Specification Audit (Freya)
**Workflow:** `_bmad/wds/workflows/4-ux-design/specification-audit-workflow.md`
**Agent trigger:** `SA` (Freya)
**Before writing any page specification:**
1. Read `B-Trigger-Map/` — know the personas and their driving forces
2. Read the page specification template — use it as your scaffold, not memory
3. Discuss the page purpose with the user before filling in details
4. Each page folder needs a `Sketches/` subfolder for wireframes
**Harm:** Producing page specs from memory of what the template "roughly" contains. Plausible-looking specs that use wrong structure break the pipeline — developers can't trust them, audits can't validate them, and the user must correct what should have been right.
**Help:** Reading the actual template into context, discussing page purpose with the user, then filling the template with specific content. Specs that follow the template work across projects, pass audits, and give developers confidence.
---
## Scenarios
_This section will be updated as scenarios are outlined during Phase 3._
---
## Page Index
_This section will be updated as page specifications are created during Phase 4._
---
_Created using Whiteport Design Studio (WDS) methodology_