Design UI architecture for team and player analytics

[Mattsface]

Goal

Design and organize the application UI so it can grow cleanly from the current team charts into both Team and Player analytics without turning the navigation into a flat list of every metric.

This issue is about information architecture, navigation, page hierarchy, and reusable presentation structure. It should establish the UI model before player charts begin multiplying.

Product model

The application will contain two primary analytics domains:

• Team analytics
• Player analytics

Each domain may eventually contain several charts and comparison views.

Examples of team views already existing or planned include:

• Hits/Game
• Batting Strikeouts/Game
• Runs/Game
• team-vs-MLB context
• season comparison
• game-result context

Player metrics are future work and must not be invented as part of this issue.

Design questions to resolve

Define a coherent answer for at least:

• What belongs in the global/top-level navigation?
• How does a user move between Team and Player analytics?
• Where do individual metrics live within each domain?
• Should Team and Player each have a landing/index page?
• Should metric navigation use tabs, a secondary nav, cards, or another simple server-rendered pattern?
• How should selectors differ between Team and Player pages?
• Which controls belong globally versus on an individual chart page?
• How should comparison views fit into the hierarchy?
• How should URLs remain understandable and shareable?
• How does the design collapse cleanly on mobile?

Preferred direction

Favor a hierarchy such as:

MLB Stats Visualizer
├── Teams
│   ├── Hits
│   ├── Strikeouts
│   ├── Runs
│   └── Comparisons
└── Players
    └── future player metrics

This is a starting point, not a mandated final layout. Inspect the actual application and propose the simplest structure that scales.

Do not keep adding every new metric directly to one flat top navigation bar.

Scope

• Audit the current navigation, templates, page shell, selectors, chart pages, responsive behavior, and route structure
• Produce a concrete information architecture for Team and Player analytics
• Establish clear global vs domain-level vs page-level navigation
• Organize existing Team charts consistently
• Define the reusable page structure future Player charts should follow
• Preserve the visual language established by the reference-layout UI work
• Keep desktop and mobile navigation usable as more metrics are added
• Preserve semantic HTML, keyboard navigation, focus states, and aria-current
• Preserve server-rendered FastAPI/Jinja and local Plotly

If implementation is included, keep it focused on navigation/page organization and reusable presentation structure.

Important constraint: no fake features

Do not add dead Player links, placeholder controls, fake charts, or routes that imply player analytics already exist.

The design may document where Player analytics will live, and the shell may be structured so they can be added cleanly later, but every visible interactive navigation item in the running application should lead to something real.

URL design

Review the current routes and propose a scalable URL scheme.

For example, consider whether the long-term shape should become something like:

/teams/hits
/teams/strikeouts
/teams/runs
/teams/compare

/players/...

Do not perform a disruptive route migration merely for aesthetics. Existing shareable URLs and query parameters should continue working or have a deliberate compatibility strategy.

Selectors

Team pages currently need concepts such as:

• Team
• Season
• Rolling Window

Future Player pages will likely need a different primary entity selector.

Design selectors so the shared page shell does not assume every analytics page is team-based.

Do not invent player-stat inputs or API behavior in this issue.

Reuse without premature abstraction

Reuse templates/partials/CSS where the UI genuinely shares structure.

Avoid building a generic frontend framework or giant configuration-driven metric system just to support two domains.

Prefer readable Jinja partials, straightforward CSS, and explicit routes.

Preserve

• existing Hits behavior
• existing Strikeouts behavior
• Runs behavior if merged by implementation time
• MLB-average COMPLETE coverage semantics
• shareable query parameters
• DB-only browser rendering
• local Plotly
• existing error and empty states
• responsive reference-layout styling

Deliverables

1. A short documented UI/information-architecture decision
2. Proposed navigation hierarchy
3. Proposed route hierarchy and compatibility plan
4. Desktop organization
5. Mobile organization
6. Selector strategy for Team vs future Player pages
7. Reusable template/CSS boundaries
8. Implementation of the agreed organization if the scope remains small enough for one PR
9. Before/after screenshots for any implemented layout changes

Testing

If implementation changes the running UI, cover at minimum:

• all existing metric routes remain reachable
• active navigation state is correct
• query parameters remain shareable
• no dead navigation links
• desktop navigation
• mobile navigation
• keyboard/focus behavior
• Hits/Strikeouts/Runs regressions
• /health unchanged
• zero MLB API calls during normal browser rendering

Out of scope

• implementing player statistics
• choosing the first player metric
• new MLB ingestion for players
• React or another frontend framework
• generic dashboard builders
• analytics/statistical redesign
• replacing Plotly

Completion

The application has a documented, scalable UI structure where users can understand the difference between Team and Player analytics, existing Team charts are organized coherently, and future Player charts have an obvious home without requiring another navigation redesign.