Skip to content

DeveloperGuide.md

Latest commit

 

History

History
70 lines (48 loc) · 4.08 KB

DeveloperGuide.md

File metadata and controls

70 lines (48 loc) · 4.08 KB

Forms Optel Dashboard — Developer Guide

This guide is for contributors and AI agents working on the project. For using the dashboard, see UserGuide.md.

Project overview

Forms Optel Dashboard (Operational Telemetry) is a browser-based analytics dashboard for Optel data for web forms, per AEM Live documentation. It reads data from the Adobe RUM bundler API and presents four views: Error Analysis, Performance, Engagement, and Resources. No build step — native ES modules and importmaps in the browser.

Stack: Vanilla JavaScript (ES2022 ESM) + Web Components + Chart.js + @adobe/rum-distiller.

Quick links

Topic Guide
Project structure (folders, files) structure.md
Code conventions (modules, DataChunks, charts, URL state) code.md
Testing (commands, E2E; manual testing temporary, being replaced by E2E) testing.md

Running the app

  • Helix project: Run aem up (AEM CLI), then open the URL shown (e.g. http://localhost:3000 or http://localhost:3232). Do not use npm start or npx serve.
  • Install AEM CLI if needed: npm install -g @adobe/aem-cli

Running tests

  • All tests: npm test
  • Unit only: npm run test:unit
  • E2E only: npm run test:e2e (see testing.md for env and credentials)
  • Lint: npm run lint — must pass before committing.

Full command reference and writing-test rules: testing.md.

Domain and resolver behavior

  • The active domain is user-editable via #domain-input + #apply-domain.
  • Applying a domain must update the domain URL query parameter without dropping other dashboard state params.
  • Domain-key resolution uses POST https://optel-alerts.audvatwork.workers.dev/domain-key with { domain, secret }.
  • Resolver secret precedence is: URL domainkey (non-empty) first, then localStorage rum-bundler-token.
  • On resolver failures/invalid payloads, render a user-facing invalid domain/domainkey error and skip bundles API loading.

Contribution workflow (Speckit)

All features MUST go through speckit. Do not write implementation code without a completed spec and plan on the current branch.

Step Command What it does
1 /speckit.specify Creates feature branch + spec.md from a description
2 /speckit.clarify (Optional) Resolves ambiguous requirements
3 /speckit.plan Generates plan.md, research.md, data-model.md, quickstart.md
4 /speckit.tasks Generates tasks.md with dependency-ordered task list
5 /speckit.implement Work through tasks.md in order
6 Raise PR Branch → PR, link to GitHub issue

Branch naming: [###-short-name] — e.g. 001-ai-centric-devx PR title: feat(###): short description or fix(###): short description

GitHub and automation

  • Issue skills: /github-read-issue <N>, /github-update-issue <N> "<comment>" (require gh CLI).
  • work-next pipeline: /work-next <N> runs the full autonomous pipeline for issue #N. See specs/009-work-next-subagents/quickstart.md for details.

Behavioural rules (agents)

  • Working on an issue: Fetch with gh issue view <N>, summarise, suggest /speckit.specify with the issue title, wait for confirmation.
  • Ad-hoc implementation: Decline; explain speckit is required; show the workflow and pre-fill /speckit.specify.
  • Current stage: Check specs/[current-branch]/ — no spec → specify; spec only → plan; spec+plan → tasks; spec+plan+tasks → implement.
  • Date handling: Always derive current date from the terminal (e.g. date +%Y-%m-%d).
  • PR review checklist: See .github/PULL_REQUEST_TEMPLATE.md; agents must self-review before marking PR ready and validate checklist when reviewing.

Full behavioural instructions and PR checklist rules are in the repository root CLAUDE.md (short entry that points here). For coding conventions, URL state, and chart/DataChunks rules, see code.md. For project layout, see structure.md.