Dashboard API Reference¶

Module: fcc.dashboard

The dashboard module provides terminal-based ASCII dashboards for ecosystem, persona, simulation, quality, and collaboration views. All renderers produce plain-text output using ANSI escape codes for colour, requiring no third-party dependencies.

flowchart LR
    Data[Data Source] --> Fmt[_formatters]
    Data --> Wdg[_widgets]
    Fmt --> R1[ecosystem dashboard]
    Fmt --> R2[personas dashboard]
    Fmt --> R3[quality dashboard]
    Fmt --> R4[simulation dashboard]
    Fmt --> R5[collab dashboard]
    Wdg --> R1
    Wdg --> R2
    R1 --> TTY[Terminal Output]
    R2 --> TTY
    R3 --> TTY
    R4 --> TTY
    R5 --> TTY

Module Structure¶

Module	Description
`fcc.dashboard._formatters`	Low-level formatting: tables, status colours, truncation
`fcc.dashboard._widgets`	Higher-level widgets: progress bars, status badges
`fcc.dashboard.ecosystem`	Ecosystem project dashboard
`fcc.dashboard.simulation`	Simulation progress dashboard
`fcc.dashboard.personas`	Persona catalog dashboard
`fcc.dashboard.quality`	Quality gate dashboard
`fcc.dashboard.collab`	Collaboration session dashboard

Formatters¶

from fcc.dashboard._formatters import format_status, format_table, truncate, format_percentage

Function	Signature	Returns	Description
`format_status()`	`(status: str)`	str	Colour-code a status string (green/red/yellow/cyan)
`truncate()`	`(text: str, max_len: int = 40)`	str	Truncate with ellipsis
`format_table()`	`(headers, rows, title=None)`	str	Render an ASCII table
`format_percentage()`	`(value: float)`	str	Format as percentage string

Known status mappings: ok/pass/passed/active/complete/completed -> green, error/fail/failed/critical -> red, warn/warning/pending -> yellow, info/running/in_progress -> cyan.

Widgets¶

from fcc.dashboard._widgets import progress_bar, status_badge

Function	Signature	Returns	Description
`progress_bar()`	`(percentage: float, width: int = 30)`	str	ASCII progress bar `[##########.....]`
`status_badge()`	`(label: str, ok: bool)`	str	`[OK] label` or `[!!] label` with colour

Usage¶

from fcc.dashboard._widgets import progress_bar, status_badge

print(progress_bar(75.0))
# [██████████████████████░░░░░░░░] 75.0%

print(status_badge("Plugin loaded", True))
# [OK] Plugin loaded

Ecosystem Dashboard¶

from fcc.dashboard.ecosystem import render_ecosystem_dashboard

Function	Signature	Returns	Description
`render_ecosystem_dashboard()`	`(projects: list[dict])`	str	Render ecosystem project table

Each dict should contain: name (str), tier (str), maturity (str), tests (int), port (str).

Usage¶

from fcc.dashboard.ecosystem import render_ecosystem_dashboard

projects = [
    {"name": "FCC Core", "tier": "L2", "maturity": "active", "tests": 2472, "port": "ok"},
    {"name": "PAOM", "tier": "L1", "maturity": "active", "tests": 850, "port": "ok"},
]
print(render_ecosystem_dashboard(projects))

Simulation Dashboard¶

from fcc.dashboard.simulation import render_simulation_dashboard

Renders simulation progress showing current node, step count, persona activations, and timing.

Persona Dashboard¶

from fcc.dashboard.personas import render_persona_dashboard

Renders a persona catalog table showing all personas with their categories, FCC phases, archetypes, and action counts.

Quality Dashboard¶

from fcc.dashboard.quality import render_quality_dashboard

Renders quality gate results showing pass/fail status, scores, and remediation status for each gate.

Collaboration Dashboard¶

from fcc.dashboard.collab import render_collab_dashboard

Renders collaboration session status showing participants, turn count, current status, and approval gate outcomes.

CLI Integration¶

The dashboards are accessible through the fcc dashboard CLI command:

# Ecosystem overview
fcc dashboard ecosystem

# Persona catalog
fcc dashboard personas

# Quality gates
fcc dashboard quality

# Collaboration sessions
fcc dashboard collab

These commands are implemented in fcc.scaffold.cli and use the dashboard renderers to produce terminal output.