+ 
@@ -48,39 +49,47 @@
**BehaviorGraph** conecta taxonomia de eventos, funis de ativação, cohorts de retenção, grafos de jornada e memos de oportunidade de produto em um estúdio analítico de lab.
-> **Aviso de lab:** demo de portfólio com dados sintéticos/amostra. Não é produto em produção com SLA, integrações reais de clientes ou garantia operacional.
+> **Aviso de lab:** demo de portfólio com dados sintéticos. Não é produto em produção com SLA, tracking real de usuários ou atribuição causal.
+
+| Item | Estado |
+|---|---|
+| Escopo | Portfolio lab / MVP (seed sintética) |
+| Live Demo | [barujafe1.github.io/BehaviorGraph](https://barujafe1.github.io/BehaviorGraph/) |
+| CI | GitHub Actions (API + Web) |
+| Tracking de produção | **Fora do escopo** |
---
## Problema
-Eventos de produto ficam em warehouses sem narrativa: sem taxonomia clara, funil e jornada não conversam com a decisão de produto.
+Produtos digitais coletam eventos, mas times ainda lutam para responder:
----
+- Quais passos de ativação perdem usuários?
+- Quais transições de sessão dominam?
+- Quais cohorts retêm depois da semana 0?
+- Onde o atrito é alto o suficiente para merecer uma aposta de produto?
-## Para quem
-
-- Product analysts e PMs analíticos
-- Growth / activation
-- Engenheiros de analytics
+Métricas de vaidade (“quantos se cadastraram?”) escondem o caminho.
---
## Funcionalidades
-- Taxonomia de eventos
-- Funis de ativação
-- Cohorts de retenção
-- Grafo de jornada (NetworkX)
-- Memos de oportunidade
-- DuckDB no backend para consultas
+- Taxonomia de eventos como contrato com owner
+- Funil de ativação aninhado (usuários únicos que permanecem dos passos anteriores)
+- Cohorts de retenção por primeira semana vista (offsets W0–W4 reais)
+- Grafo de jornada (transições de sessão via NetworkX)
+- Segmentos + radar de atrito com severidade (`low` / `medium` / `high`)
+- Memo de oportunidade (ação + hipótese de impacto + limites)
+- Snapshot estático para demos públicas confiáveis
+- Backend FastAPI opcional para execução full-stack local
---
## Escopo e limites
- **É:** estúdio lab de behavioral analytics.
-- **Não é:** Amplitude/Mixpanel clone, CDP, tracking SDK de produção.
+- **Não é:** clone de Amplitude/Mixpanel, CDP, SDK de tracking de produção, ferramenta causal.
---
@@ -92,39 +101,40 @@ Eventos de produto ficam em warehouses sem narrativa: sem taxonomia clara, funil
**BehaviorGraph** connects event taxonomy, activation funnels, retention cohorts, journey graphs and product opportunity memos in one analytics studio lab.
-> **Lab notice:** portfolio demo with synthetic/sample data. Not a production product with SLA, real customer integrations, or operational guarantees.
+> **Lab notice:** portfolio demo with synthetic data only. Not production telemetry, not Mixpanel, and not causal attribution.
---
## Problem
-Product events sit in warehouses without narrative: without clear taxonomy, funnel and journey never meet product decisions.
-
----
+Digital products collect events, but teams still struggle to answer:
-## Who it is for
+- Which activation steps lose users?
+- Which session transitions dominate?
+- Which cohorts retain after week 0?
+- Where is friction high enough to deserve a product bet?
-- Product analysts and analytical PMs
-- Growth / activation
-- Analytics engineers
+Conversion vanity metrics (“how many signed up?”) hide the path.
---
-## Features
+## Core features
-- Event taxonomy
-- Activation funnels
-- Retention cohorts
-- Journey graph (NetworkX)
-- Opportunity memos
-- DuckDB on the backend for queries
+- Event taxonomy as an owned contract
+- Nested unique-user activation funnel (+ conversion from start)
+- Retention cohorts with true W0–W4 offsets
+- Journey graph edges with weights (NetworkX)
+- Segments + friction severity bands
+- Opportunity memo (action + impact hypothesis + limits)
+- Static lab snapshot for reliable public demos
+- Optional FastAPI backend for local full-stack runs
---
## Scope and limits
- **Is:** behavioral analytics studio lab.
-- **Is not:** Amplitude/Mixpanel clone, CDP, production tracking SDK.
+- **Is not:** Amplitude/Mixpanel clone, CDP, production tracking SDK, causal tool.
---
@@ -136,7 +146,34 @@ Product events sit in warehouses without narrative: without clear taxonomy, funn
Demo hospedada para avaliação de portfólio / Hosted for portfolio review.
-> Lab demo — synthetic / sample data unless noted. Not a production SLA product.
+> Lab demo — synthetic data only. Not a production SLA product.
+
+---
+
+## Screenshots
+
+
+ 
+ 
+ 
+ 
+Users
-{demo?.users ?? "—"}
- Portfolio lab · synthetic events · responsible analytics
BehaviorGraph
- MVP lab that turns product events into taxonomy, activation funnel, - retention cohorts, journey graph and an opportunity memo — answering - which paths lead to activation, abandonment or recurring use. + Turns product events into taxonomy, nested activation funnel, retention + cohorts, journey graph and an opportunity memo — answering which paths + lead to activation, abandonment or recurring use.
-- {demo?.notice} -
-
+
+ Synthetic seed
+
+
+ Nested unique-user funnel
+
+
+ No causal overclaim
+
+
+ {demo?.notice}
+ - {error ?{error}
: null}
- {pending && !demo ? Loading lab snapshot…
: null} + -Events
-{demo?.events ?? "—"}
- Sessions
-{demo?.sessions ?? "—"}
- Activation rate
-
- {demo ? `${Math.round(demo.activation_rate * 100)}%` : "—"}
-
-
+ {error}
+
+ ) : null}
+
+ {pending && !demo ? Event taxonomy
--
- {taxonomy.slice(0, 8).map((ev) => (
-
-
- {ev.event_name}{" "}
- {ev.category}
-
- {ev.description} · owner: {ev.owner} -
- ))}
-
+ Owned event contract — category, description and owner before volume. +
+ {taxonomy.length ? ( +-
+ {taxonomy.map((ev) => (
+
-
+ {ev.event_name}{" "}
+ {ev.category}
+
+ {ev.description} · owner: {ev.owner} +
+ ))}
+
Taxonomy not loaded.
+ )}Activation funnel
- {funnel.map((step) => ( -
- {step.step}
-
- ))}
+
-
-
- {step.users}
- + Nested unique users (must remain in the previous step set). Method is + explicit — not raw event counts. +
+-
+ {funnel.map((step) => (
+
- + {step.step} — {step.users} users ·{" "} + {Math.round(step.conversion_from_previous * 100)}% from previous + {typeof step.conversion_from_start === "number" + ? ` · ${Math.round(step.conversion_from_start * 100)}% from start` + : ""} + + ))} +
Retention cohorts
--
- {cohorts.slice(0, 5).map((c) => {
- const w1 = c.weeks.find((w) => w.week_offset === 1);
- return (
-
- - {c.cohort_week} — size {c.cohort_size} - {w1 - ? ` · W1 retention ${Math.round(w1.retention_rate * 100)}%` - : ""} - - ); - })} -
+ First-seen week cohorts with true week offsets (W0–W4). +
+Segments
++ Lightweight behavioral slices for product conversation — not ML scoring. +
-
{segments.map((s) => (
-
- {s.name} — {s.users} users · {s.definition}
+ {s.name} — {s.users} users
+
+ {s.definition}
))}
Journey path graph
-- Top session transitions · {journey?.edges.length ?? 0} edges · engine{" "} - {journey?.engine ?? "snapshot"} +
+ Top session transitions via NetworkX. Exploratory map — not Markov + attribution or causal path proof. +
++ {journey?.edges.length ?? 0} edges · engine {journey?.engine ?? "snapshot"}
-
{(journey?.edges ?? []).slice(0, 12).map((e) => (
- - {e.source} → {e.target}{" "} - w={e.weight} + {e.source} → {e.target} w={e.weight} ))}
Friction radar
++ Drop severity on the nested funnel plus error-like signals. +
+ {topDrop ? ( ++ Largest drop: {topDrop.from_step} →{" "} + {topDrop.to_step} ( + {Math.round(topDrop.drop_rate * 100)}%, {topDrop.severity}) +
+ ) : null}-
{(friction?.funnel_drops ?? []).map((d) => (
-
@@ -184,26 +242,43 @@ export default function HomePage() {
{d.from_step} → {d.to_step}
- drop {Math.round(d.drop_rate * 100)}% · severity {d.severity} + drop {Math.round(d.drop_rate * 100)}% ·{" "} + {d.severity}
))}
Error-like signals
+-
+ {friction!.error_signals.map((s) => (
+
- + {s.event_name}: {s.affected_users} users + + ))} +
Product opportunity memo
--
+
-
- {o.title}
-
- {o.why} -
- Action: {o.suggested_action} -
+ - {l} @@ -211,6 +286,13 @@ export default function HomePage() {
+ Hypotheses tied to observed drops — with explicit analytical limits. +
+
{(memo?.opportunities ?? []).map((o) => (
-
+
+
))}
-
- {o.title}
+{o.why}
++ Action: {o.suggested_action} +
+{o.impact_hypothesis}
+Limitations
+Limitations
-
{(memo?.limitations ?? []).map((l) => (