Skip to content

Create portal UI information architecture #43

Closed
Closed
Create portal UI information architecture#43
Labels
P0Must haveassistantAssistant modules and jobsdesignDesign and UXdocsDocumentation or process docs workenhancementNew or improved functionalityfrontendFrontend UIportalShared portal shell and UXtestingTests and QAwork-engineDataTasks task execution engine

Description

@alexeygrigorev
alexeygrigorev
opened on Jun 27, 2026

Implement V1 portal information architecture for daily operations

Status: pending
Tags: enhancement, portal, frontend, work-engine, assistant, docs, design, testing, P0
Depends on: #10, #46, #55
Blocks: #44

Scope

Implement the V1 portal information architecture so DataOps is a workflow-first daily operations workspace for the DataTalksClub operations manager, not a docs browser with task links bolted on.

The central product reference is docs/operations-manager-platform-jtbd.md. The IA must make the operator's daily jobs easy to perform in one place:

  1. See today's work, overdue work, waiting work, follow-ups due, and at-risk workflows.
  2. Open a workflow and understand the next action, stage, missing evidence, and waiting items.
  3. Complete task work only when required proof is present.
  4. Use SOPs, templates, and reference docs in context at the task or workflow step.
  5. Review assistant outputs and artifacts as workflow evidence, not as disconnected generated files.
  6. Avoid switching between separate DataTasks, docs, assistant, and artifact mental models for normal operations.

This issue should define and implement the first portal IA layer across the existing frontend/ portal and the current work-engine surfaces exposed through /work/api/*. It should use #10's shipped Operations Home as the daily command center, #46's design-system vocabulary as the component/navigation language, and #55's shell-token work as the shell baseline. If #55 is still in progress when implementation starts, sequence this issue after it or explicitly rebase on its shell changes before final verification.

The implementation should produce a coherent page/navigation hierarchy and user flow, not just rename navigation labels. It may include a short durable IA note under docs/ if that helps future PM/Designer/SWE work stay aligned, but the primary deliverable is the operator-facing portal IA behavior.

Required IA Shape

Workflow-first navigation

The primary portal navigation should prioritize operating work before process browsing. The exact labels can follow implementation constraints, but the hierarchy must support these destinations and relationships:

  • Operations Home: default daily landing page after login and the default way back to active work.
  • Work Queue or equivalent task view: cross-workflow tasks with date/status/assignee/source filters for inspection beyond today.
  • Workflows: active workflow bundle list and workflow detail entry points.
  • Templates / Recurring: starting known workflows and configuring periodic operations.
  • Assistants: assistant job/status surface for recent, running, failed, and approval-needed jobs when the backing model exists; otherwise an honest not-connected state that points to Implement assistant job model and lifecycle #30/Implement Podcast Assistant portal UI in workflow context #44 without fake jobs.
  • Artifacts: proof and generated output surface for files, links, assistant outputs, approvals, and review status when artifact data exists; otherwise an honest empty state.
  • Processes: SOP/template/reference library for contextual lookup, secondary to daily work.
  • Search: global search affordance that can find work and docs where available; docs-only search must be clearly scoped until broader search exists.
  • Admin: lower-priority operational maintenance such as recurring configs, template editing, users, diagnostics, git/content tools, or other maintainer-only actions already present in the app.

Navigation must make DataOps feel like one workspace. Do not expose the legacy DataTasks top-nav mental model as a separate product path in the portal IA.

Operations Home

Operations Home remains the default daily command center from #10. This issue should make its position in the IA explicit and ensure the surrounding navigation reinforces the daily loop from the JTBD:

  • Start with Today, Overdue, Waiting / Follow-ups, and At-risk workflows before docs or admin tooling.
  • Show concrete next actions from cards or rows: complete, add link, attach/upload proof, approve artifact, follow up, mark response received, open workflow, start workflow, or open instructions.
  • Include quick entry points for ad-hoc task creation and starting a workflow from a template if those controls exist in the current portal/work-engine integration.
  • Keep inbox, assistant jobs, process quality, and other future areas integrated as honest states without fake data.

Workflow and task detail

The IA must make workflow detail the main execution surface for a concrete operation such as a newsletter, podcast, webinar, workshop, book-of-the-week, sponsor workflow, or monthly tax report.

Workflow detail must expose, or preserve clear entry points for:

  • workflow header with title, type, stage, anchor date, status/risk indicators, progress, next due task, overdue count, waiting/follow-up count, and missing evidence count where data supports it;
  • required workflow links such as Luma, Meetup, YouTube, Mailchimp, sponsor doc, Airtable, Dropbox, schedule spreadsheet, invoice folder, or website URL;
  • active tasks grouped ahead of done history;
  • waiting tasks and due follow-ups that do not disappear into generic todo state;
  • proof requirements and missing evidence before completion;
  • assistant jobs and artifacts linked to the workflow or its tasks;
  • fixed process references and task-specific instructions;
  • ad-hoc task attachment to the workflow where existing APIs/UI support it;
  • comments/audit/history entry points where available.

Task detail must expose the operator actions from the JTBD:

  • complete task only when required proof is satisfied;
  • save required URL proof;
  • attach or inspect required file/artifact proof where available;
  • approve/reject artifact proof where the artifact API supports it;
  • mark waiting with waitingFor, followUpAt, and note;
  • record follow-up sent and set next follow-up date;
  • mark response received and return work to todo;
  • open workflow context;
  • open the relevant SOP/template/reference in context.

Docs in context

Docs must support workflow execution. They must not be the main daily operating model.

Implement the IA so:

  • task rows/detail expose direct instruction links when a task/template has mapped SOPs or references;
  • workflow detail exposes fixed process references near the relevant tasks or links;
  • opening a doc from a task/workflow keeps the operator oriented and gives a clear route back to the task/workflow;
  • process search remains available for unmapped questions, but it is secondary to task/workflow context;
  • GitHub/content editing tools remain lower-priority maintainer/admin actions, not primary operator navigation;
  • a future Report process gap action has an obvious home in the task/workflow context, even if the durable gap workflow is not implemented in this issue.

Assistant and artifact surfaces

Assistant and artifact IA must use the same workflow/task/proof model as the rest of the portal.

  • Assistant jobs are contextual support for workflows and tasks. They are not a separate assistant app.
  • Assistant outputs become artifacts and can satisfy task proof only when the task/workflow explicitly accepts that artifact type and the artifact is approved.
  • The portal must provide an obvious place for assistant jobs needing review, failed jobs, retry/cancel states, and approved outputs when Implement assistant job model and lifecycle #30 data is available.
  • Until Implement assistant job model and lifecycle #30/Implement Podcast Assistant portal UI in workflow context #44 are implemented, the Assistants surface must render an honest not-connected or empty state with no fake jobs, fake counts, or disconnected workflow.
  • Artifact rows should expose title, type/source, status, linked task/workflow, storage/link target, review state, and available review actions using the current artifact API where available.
  • Rejected or archived artifacts must not appear as proof-ready completion evidence.

Responsive behavior

Use #46/#55 design-system rules and preserve Pixel 7 as the mobile baseline.

  • Desktop: persistent sidebar/workspace navigation, Operations Home lanes above the fold, workflow/task detail as a right panel or reserved detail region that does not obscure headings/actions.
  • Tablet: sidebar can collapse to rail or drawer; detail panels may overlay only with intentional focus and Escape behavior.
  • Pixel 7-sized mobile: show one primary state at a time: navigation drawer, Operations Home, work queue, workflow detail, task detail, doc context, assistant review, or artifact review.
  • Mobile task/workflow detail should have a compact back action and must not require scrolling past long docs/search/admin controls before reaching active work.
  • Drawer, modal, popover, task panel, workflow panel, assistant panel, and artifact review surfaces need keyboard/focus behavior consistent with Create shared DataOps design system and component tokens #46/Apply shared DataOps shell tokens and primitives to the V1 portal shell #55.

Sequencing inside this issue

Implement in this order unless the codebase suggests a safer equivalent:

  1. Confirm Apply shared DataOps shell tokens and primitives to the V1 portal shell #55 shell-token changes are present or merge/rebase implementation work onto them.
  2. Establish the workflow-first navigation model in the portal shell and ensure Operations Home is the default daily destination.
  3. Align Operations Home entry points with the concrete JTBD next actions and downstream detail surfaces.
  4. Align task detail and workflow detail hierarchy around proof, waiting/follow-up, artifacts, and docs-in-context.
  5. Add or align Assistants and Artifacts IA surfaces with honest empty/not-connected states when backing data is missing.
  6. Verify responsive desktop, tablet, and Pixel 7 mobile flows with screenshots.

Acceptance Criteria

  • Portal navigation is workflow-first: Operations Home, work/tasks, workflows, templates/recurring, assistants, artifacts, processes/docs, search, and admin/maintenance are represented in a coherent hierarchy, with daily work before docs/admin tooling.
  • Operations Home remains the default daily landing surface and provides clear IA entry points for today, overdue, waiting/follow-ups, at-risk workflows, quick task creation, workflow start, assistant/artifact review states, and contextual process docs.
  • The IA supports the concrete daily tasks from docs/operations-manager-platform-jtbd.md: check overdue work, check follow-ups due, check today tasks, review active workflow risks, update proof links/files/artifacts, follow up with people who have not replied, create/update tasks from incoming work, and review tomorrow's urgent work.
  • Workflow cards and workflow detail expose stage, anchor date, progress, next due task, overdue count, waiting/follow-up count, required links, missing proof/artifact risk, active task checklist, waiting items, done history, assistant/artifact references, and process references where current data supports those fields.
  • Task detail exposes the operator's next actions: mark done, save required link, inspect/attach proof, approve artifact proof where available, mark waiting, set follow-up, record follow-up sent, mark response received, open workflow, and open instructions.
  • Proof-gated completion remains visible in the IA: tasks with required URL, file, artifact, comment, or external-status proof cannot appear ready to complete until the required evidence is present and approved where required.
  • Waiting and follow-up work remains visible in both Operations Home and workflow/task detail; waiting tasks require or expose waitingFor, followUpAt, and a note/history path where the current model supports it.
  • Docs are exposed in context from tasks/workflows and remain secondary in the primary IA; opening docs from work context provides a clear path back to the task/workflow.
  • Assistants and Artifacts surfaces are represented as workflow-linked operational surfaces. When Implement assistant job model and lifecycle #30/Implement Podcast Assistant portal UI in workflow context #44 backing data is missing, they render honest empty/not-connected states without fake data.
  • Artifact rows/review controls, where implemented, show artifact status and prevent rejected/archived/non-approved artifacts from satisfying proof-ready UI states.
  • Search behavior is scoped honestly: docs-only search is labeled as such until broader task/workflow/artifact search exists, and search does not replace direct work navigation.
  • Admin/maintenance tools such as template editing, recurring configuration, git/content tools, diagnostics, or user management are lower-priority paths and do not compete with the daily operating loop.
  • Desktop, tablet, and Pixel 7-sized mobile layouts preserve one clear primary state at a time; no task/workflow/doc/assistant/artifact controls overlap, become unreachable, or hide the main next action.
  • Keyboard and focus behavior is preserved or improved for navigation drawer, task/workflow panels, assistant/artifact surfaces, modals, popovers, and actionable cards/rows.
  • Implementation reuses Create shared DataOps design system and component tokens #46/Apply shared DataOps shell tokens and primitives to the V1 portal shell #55 design-system vocabulary and does not introduce a second visual/component language for assistant, artifact, or work-engine-derived surfaces.
  • Tests cover the changed navigation hierarchy, route/view switching, Operations Home entry points, task/workflow detail links, docs-in-context links, assistant/artifact empty or data-backed states, and responsive-critical behavior that can be tested without screenshots.
  • Tester captures and inspects screenshots for the changed IA on desktop and Pixel 7-sized mobile, including Operations Home, navigation/drawer, task detail, workflow detail, docs-in-context, Assistants, and Artifacts states.

Test Scenarios

Scenario: Operator starts the day from one queue

Given: the operator is authenticated and live work data is available through /work/api/*.
When: they open the portal after login.
Then: Operations Home is the default destination, daily work appears before docs/admin tools, and the operator can open Today, Overdue, Waiting / Follow-ups, and At-risk workflow items without leaving the portal.

Scenario: Operator follows up on waiting work

Given: a task is waiting for a guest, sponsor, author, speaker, publisher, freelancer, reviewer, or Alexey and followUpAt is today or earlier.
When: the operator opens Operations Home and then task detail.
Then: the task is presented as follow-up due, shows who it is waiting for, exposes record-follow-up and response-received actions where implemented, and links back to its workflow context.

Scenario: Operator completes proof-gated work

Given: a task requires a public event URL, social post link, invoice file, recording/transcript artifact, assistant output, comment, or external status proof.
When: the operator tries to complete it from the task or workflow detail.
Then: completion is blocked until the required proof is present, the missing proof is named, and approved artifact proof is accepted only when the artifact status permits it.

Scenario: Operator opens a workflow to move it forward

Given: an active newsletter, podcast, webinar, workshop, book-of-the-week, sponsor, or monthly tax workflow has tasks, required links, waiting items, and process references.
When: the operator opens the workflow from Operations Home or the Workflows area.
Then: workflow detail shows stage/progress/risk first, then required links and active/waiting tasks, with done history and process docs available without becoming the primary screen.

Scenario: Operator uses an SOP at the moment of need

Given: a task has a mapped instruction document or fixed process reference.
When: the operator opens the instructions from task or workflow detail.
Then: the relevant SOP/template/reference opens in context, the operator can return to the task/workflow, and the main navigation still treats docs as process support rather than the daily landing area.

Scenario: Operator reviews assistant output as workflow evidence

Given: assistant job or artifact data exists for a workflow/task.
When: the operator opens Assistants, Artifacts, task detail, or workflow detail.
Then: assistant outputs appear as linked operational artifacts with status/review context, and only approved artifacts can satisfy artifact proof requirements.

Scenario: Assistant backing model is not ready

Given: #30/#44 assistant job UI data is unavailable or not implemented in the current environment.
When: the operator opens the Assistants surface or sees Assistant Jobs on Operations Home.
Then: the portal shows an honest not-connected/empty state with no fake jobs, fake counts, or broken navigation.

Scenario: Mobile operator opens workflow detail

Given: a Pixel 7-sized viewport.
When: the operator opens navigation, Operations Home, a task detail, a workflow detail, a doc context view, and an assistant/artifact review state.
Then: only one primary state is visible at a time, back/dismiss actions are available, touch targets remain usable, and no long docs/search/admin controls block the active work action.

Scenario: Work-engine remains integrated

Given: current work-engine task, bundle, template, recurring, notification, artifact, and future assistant concepts remain behind /work/api/*.
When: the portal IA links to those concepts.
Then: the operator experiences them as DataOps work surfaces, not as a separate DataTasks product or disconnected route set.

Out of Scope

  • Rebuilding the Operations Home data model already completed in Complete the first Operations Home dashboard #10, except for IA/navigation adjustments needed by this issue.
  • Implementing the full assistant job lifecycle, durable logs, retries, approvals, or production runner integration; that belongs to Implement assistant job model and lifecycle #30 and Implement Podcast Assistant portal UI in workflow context #44.
  • Implementing a new artifact storage policy or binary upload backend beyond current artifact metadata/review surfaces.
  • Implementing a durable inbox model for Telegram, email, manual notes, files, and assistant-ready inputs.
  • Replacing the current plain HTML/CSS/JavaScript stack or choosing a new frontend framework.
  • Large backend/API rewrites unless a narrow route or field exposure is required to connect the IA to existing work-engine data.
  • Public DataTalksClub marketing navigation, public website IA, or brand redesign.
  • Modifying source repositories outside dataops, including ../dtc-operations, ../datatasks, and ../podcast-assistant.
  • Production external-system writes, real Telegram/Heru/Codex/Claude execution, sponsor/client messaging, or destructive production data checks.

Dependencies

  • Complete the first Operations Home dashboard #10 provides the shipped Operations Home daily loop and must remain the behavioral base.
  • Create shared DataOps design system and component tokens #46 provides the design-system tokens, components, responsive rules, and assistant/artifact reuse language.
  • Apply shared DataOps shell tokens and primitives to the V1 portal shell #55 should be completed first or coordinated closely so this IA work builds on the shared portal shell tokens instead of conflicting with them.
  • docs/operations-manager-platform-jtbd.md is the primary product acceptance reference for operator jobs, concrete tasks, and non-goals.
  • .goal-v1.md remains the V1 goal reference: unified daily operations workspace, proof-gated task closure, docs in context, recurring work, and assistant artifacts attached to workflows.
  • Current work-engine entities and APIs should be reused where available: tasks, bundles/workflows, templates, recurring configs, notifications, files, artifacts, waiting/follow-up fields, proof requirements, and assistant job refs.

Verification Expectations

Run the full relevant frontend/docs/work-engine workflow for touched surfaces. At minimum, expected verification should include:

node --check frontend/src/app.js
uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app
npm --prefix work-engine test
npm --prefix work-engine run typecheck

If work-engine UI, routing, generated HTML, artifact behavior, or assistant-job surfaces are changed, also run the relevant focused and/or full Playwright workflow:

npm --prefix work-engine run test:e2e

Tester must capture screenshots under .tmp/screenshots/ and inspect them for 404s, blank states, text overlap, broken layout, hidden actions, and disconnected-tool regressions. Required screenshot coverage:

  • desktop Operations Home with workflow-first navigation visible;
  • desktop task detail with proof/waiting/docs context visible;
  • desktop workflow detail with required links, active/waiting/done task grouping, artifacts/assistant references, and process references where data exists;
  • desktop Assistants and Artifacts surfaces, including honest empty/not-connected states when applicable;
  • Pixel 7-sized mobile navigation drawer;
  • Pixel 7-sized mobile Operations Home;
  • Pixel 7-sized mobile task detail or workflow detail;
  • Pixel 7-sized mobile docs-in-context or assistant/artifact review state.

If a screenshot or E2E check cannot run in the local environment, Tester must state the missing dependency and provide the strongest available alternative evidence, such as Node Playwright screenshots, focused DOM tests, or source-backed verification.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P0Must haveassistantAssistant modules and jobsdesignDesign and UXdocsDocumentation or process docs workenhancementNew or improved functionalityfrontendFrontend UIportalShared portal shell and UXtestingTests and QAwork-engineDataTasks task execution engine

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions