at-container-registry/docs/APPVIEW-UI-FUTURE.md

# ATCR UI - Feature Roadmap

This document tracks the status of ATCR features beyond the V1 MVP. Features are marked with their current status:

- **DONE** — Fully implemented and shipping
- **PARTIAL** — Some parts implemented
- **BACKEND ONLY** — Backend exists, no UI yet
- **NOT STARTED** — Future work
- **BLOCKED** — Waiting on external dependency

---

## What's Already Built (not in original roadmap)

These features were implemented but weren't in the original future features list:

| Feature | Location | Notes |
|---------|----------|-------|
| **Billing (Stripe)** | `pkg/billing/` | Checkout sessions, customer portal, subscription webhooks, tier upgrades. Build with `-tags billing`. |
| **Garbage collection** | `pkg/hold/gc/` | Mark-and-sweep for orphaned blobs. Preview (dry-run) and execute modes. Triggered from hold admin UI. |
| **libSQL embedded replicas** | AppView + Hold | Sync to Turso, Bunny DB, or self-hosted libsql-server. Configurable sync interval. |
| **Hold successor/migration** | `pkg/hold/` | Promote a hold as successor to migrate users to new storage. |
| **Relay management** | Hold admin | Manage firehose relay connections from admin panel. |
| **Data export** | `pkg/appview/handlers/export.go` | GDPR-compliant export of all user data from AppView + all holds where user is member/captain. |
| **Dark/light mode** | AppView UI | System preference detection, toggle, localStorage persistence. |
| **Credential helper install page** | `/install` | Install scripts for macOS/Linux/Windows, version API, Homebrew formula (`Formula/`), self-updating from tangled releases. |
| **Stars** | AppView UI | Star/unstar repos stored as `io.atcr.sailor.star` ATProto records, counts displayed, starred-repos page at `/u/{handle}/starred`. |
| **Label service** | `pkg/labeler/`, `cmd/labeler/` | Standalone labeler for takedowns by DID/handle/repo/AT URI with audit trail. Holds listen for takedown labels; GC defers deletion for a grace period in case of reversal. |
| **Helm chart UI** | AppView UI | Chart-aware digest page: Chart.yaml metadata, dependencies, helm install/pull command switcher (`handlers/digest_content.go`, `holdclient/helm_config.go`). |
| **AI Image Advisor** | `pkg/appview/handlers/image_advisor.go` | Claude-powered image analysis (config + SBOM + vulns) for paid users. Gated on billing + `ClaudeAPIKey`. Suggestions cached in `advisor_suggestions` table. CLI companion at `cmd/image-advisor`. |
| **Go vanity import paths** | `pkg/appview/middleware/goimport.go` | `go install atcr.io/...` meta tags, browser visits redirect to source repo. Seamark-branded credential helper variant (`cmd/credential-helper/seamark`) and theme (`themes/seamark/`). |

---

## Advanced Image Management

### Multi-Architecture Image Support — DONE (display) / NOT STARTED (creation)

**Display image indexes — DONE:**
- Show when a tag points to an image index (multi-arch manifest) — `IsMultiArch` flag, "Multi-arch" badge
- Display all architectures/platforms in the index — platform badges (e.g., linux/amd64, linux/arm64)
- Allow viewing individual manifests within the index
- Show platform-specific details

**Image index creation — NOT STARTED:**
- UI for combining multiple single-arch manifests into an image index
- Automatic platform detection from manifest metadata
- Validate that all manifests are for the same image (different platforms)

### Layer Inspection & Visualization — PARTIAL

**Layer details — DONE:**
- Digest page shows per-layer Dockerfile commands (from OCI config history), sizes, media types, empty-layer toggle (`handlers/digest.go`, `partials/layers-section.html`)
- Layer diff between two tags/digests: shared/rebuilt/added/removed via LCS on layer commands, with size delta summary (`handlers/diff.go`, `/diff/{handle}/{repo}?from=&to=`)
- Multi-arch aware: diff resolves platform children, intersects common platforms

**NOT STARTED:**
- Compression ratio display
- File changes within each layer (added/modified/deleted files)
- Layer deduplication stats (shared layers across images, storage savings)

### Image Operations — PARTIAL (delete only)

**Tag/manifest deletion — DONE:**
- Delete tags with `DeleteTagHandler` (cascade + confirmation modal)
- Delete manifests with `DeleteManifestHandler` (handles tagged manifests gracefully)

**Tag Management — NOT STARTED:**
- Tag promotion workflow (dev → staging → prod)
- Tag aliases (multiple tags → same digest)
- Tag patterns (auto-tag based on git commit, semantic version, date)
- Tag protection (mark tags as immutable)

**Image Copying — NOT STARTED:**
- Copy image from one repository to another
- Copy image from another user's repository (fork)
- Bulk copy operations

**Image History — NOT STARTED:**
- Timeline view of tag changes
- Rollback functionality
- Audit log of image operations

### Vulnerability Scanning — DONE (backend + UI)

**Backend — DONE:**
- Separate scanner service (`scanner/` module) with Syft (SBOM) + Grype (vulnerabilities)
- WebSocket-based job queue connecting scanner to hold service
- Priority queue with tier-based scheduling (quartermaster > bosun > deckhand)
- Scan results stored as ORAS artifacts in S3, referenced in hold PDS
- Automatic scanning dispatched by hold on manifest push
- See `docs/SBOM_SCANNING.md`

**AppView UI — DONE:**
- CVE count by severity badge (critical, high, medium, low) — `handlers/scan_result.go`, `partials/vuln-badge.html`
- Detailed CVE view: description, severity, affected packages, fix versions, NVD/GitHub advisory links — `handlers/vuln_details.go`, `partials/vuln-details.html`
- Vulnerability diff across tags/versions: fixed vs new vs unchanged, summarized by severity — `handlers/diff.go`
- Scan-completion webhooks (`scan:first`, `scan:all`, `scan:changed`) — see Webhooks section

**NOT STARTED:**
- Filter images by vulnerability status (in search/browse)
- Subscribe to CVE notifications for your images (beyond scan webhooks)

### Image Signing & Verification — NOT STARTED (concept + examples only)

Consolidated research/POC doc at `docs/research/IMAGE_SIGNING.md` plus example verify scripts and trust policy template in `examples/verification/` (reference an unbuilt `atcr-verify` CLI). No cosign/sigstore integration or active signing implementation.

- Sign images
- Display signature verification status
- Display signature metadata
- Require signatures for protected repositories

### SBOM (Software Bill of Materials) — DONE (backend) / PARTIAL (UI)

**Backend — DONE:**
- Syft generates SPDX JSON format SBOMs
- Stored as ORAS artifacts (referenced via `artifactType: "application/spdx+json"`)
- Blobs in S3, metadata in hold's PDS
- Accessible via ORAS CLI and hold XRPC endpoints

**UI — DONE:**
- Package list with names, versions, licenses, package types — `handlers/sbom_details.go`, `partials/sbom-details.html`
- Export: copy as CSV, download raw SPDX JSON
- Compare SBOMs across versions: Packages tab on the diff page with changed/added/removed/unchanged sections — `computeSbomDiff` in `handlers/diff.go`

**NOT STARTED:**
- Link to upstream package sources

---

## Hold Management Dashboard — DONE (on hold admin panel)

Hold management is implemented as a separate admin panel on the hold service itself (`pkg/hold/admin/`), not in the AppView UI. This makes sense architecturally — hold owners manage their own holds.

### Hold Discovery & Registration — PARTIAL

**Hold registration — DONE:**
- Automatic registration on hold startup (captain + crew records created in embedded PDS)
- Auto-detection of region from cloud metadata

**NOT STARTED:**
- UI wizard for deploying hold service
- One-click deployment to cloud platforms
- Configuration generator
- Test connectivity UI

### Hold Configuration — DONE (admin panel)

**Hold settings — DONE (hold admin):**
- Toggle public/private flag
- Toggle allow-all-crew
- Toggle Bluesky post announcements
- Set successor hold DID for migration
- Writes changes back to YAML config file

**Storage config — YAML-only:**
- S3 credentials, region, bucket, endpoint, CDN pull zone all configured via YAML
- No UI for editing S3 credentials or rotating keys

**Quotas — DONE (read-only UI):**
- Tier-based limits (deckhand 5GB, bosun 50GB, quartermaster 100GB)
- Per-user quota tracking and display in admin
- Not editable via UI (requires YAML change)

**NOT STARTED:**
- Retention policies (auto-delete old blobs)
- Hold service log viewer

### Crew Management — DONE (hold admin panel)

**Implemented in `pkg/hold/admin/handlers_crew.go`:**
- Add crew by DID with role, permissions (`blob:read`, `blob:write`, `crew:admin`), and tier
- Crew list showing handle, role, permissions, tier, usage, quota
- Edit crew permissions and tier
- Remove crew members
- Bulk JSON import/export with deduplication (`handlers_crew_io.go`)

**NOT STARTED:**
- Invitation links (OAuth-based, currently must know DID)
- Invite by handle (currently DID-only)
- Crew request workflow (users can't self-request access)
- Approval/rejection flow

### Hold Analytics — PARTIAL

**Storage metrics — DONE (hold admin):**
- Total blobs, total size, unique digests
- Per-user quota stats (total size, blob count)
- Top users by storage (lazy-loaded HTMX partial)
- Crew count and tier distribution

**NOT STARTED:**
- Access metrics (downloads, pulls, bandwidth)
- Growth over time charts
- Cost estimation
- Geographic distribution
- Access logs

---

## Discovery & Social Features

### Federated Browse & Search — PARTIAL

**Basic search — DONE:**
- Full-text search across handles, DIDs, repo names, and annotations
- Search UI with HTMX lazy loading and pagination
- Navigation bar search component

**NOT STARTED:**
- Filter by user, hold, architecture, date range
- Sort by popularity, recency, size
- Advanced query syntax
- Popular/trending images
- Categories and user-defined tags

### Sailor Profiles — PARTIAL

**Public profile page — DONE:**
- `/u/{handle}` shows user's avatar, handle, DID, and all public repositories
- OpenGraph meta tags and JSON-LD structured data

**NOT STARTED:**
- Bio/description field
- Website links
- Statistics (total images, total pulls, joined date)
- Pinned/featured repositories

### Social Features — PARTIAL (stars only)

**Stars — DONE:**
- Star/unstar repositories stored as `io.atcr.sailor.star` ATProto records
- Star counts displayed on repository pages
- Starred repositories page at `/u/{handle}/starred`

**NOT STARTED:**
- Follow other sailors
- Comment on images
- Like/upvote images
- Activity feed
- Federated timeline / custom feeds
- Sharing to Bluesky/ATProto social apps

---

## Access Control & Permissions

### Hold-Level Access Control — DONE

- Public/private hold toggle (admin UI + OCI enforcement)
- Crew permissions: `blob:read`, `blob:write`, `crew:admin`
- `blob:write` implicitly grants `blob:read`
- Captain has all permissions implicitly
- See `docs/BYOS.md`

### Repository-Level Permissions — BLOCKED

- **Private repositories blocked by ATProto** — no private records support yet
- Repository-level permissions, collaborator invites, read-only tokens all depend on this
- May require proxy layer or encrypted blobs when ATProto adds private record support

### Team/Organization Accounts — NOT STARTED

- Organization accounts, RBAC, SSO, audit logs
- Likely a later-stage feature

---

## Analytics & Monitoring

### Dashboard — PARTIAL

**Hold dashboard — DONE (hold admin):**
- Storage usage, crew count, tier distribution

**Personal dashboard — NOT STARTED:**
- Overview of your images, holds, activity
- Quick stats, recent activity, alerts

### Pull Analytics — PARTIAL

**DONE:**
- Pull/push counts per repository stored in AppView DB (`repository_stats`), with daily time-series snapshots (`repository_stats_daily`)
- Pull counts displayed on repo cards, repository pages, and OpenGraph metadata

**NOT STARTED:**
- Growth/time-series charts (daily data is collected but not visualized)
- Per-tag breakdown
- Pull count by client, geography
- User analytics (authenticated vs anonymous)

### Alerts & Notifications — PARTIAL

**DONE:**
- Storage quota alerts in settings UI (warning states at 80%, 95%, 100% usage) — `partials/storage_stats.html`
- Quota threshold webhooks and scan-completion webhooks, with Discord/Slack formatting — see Webhooks section

**NOT STARTED:**
- Email notifications
- ATProto/DM notification channel
- Hold-down alerts

---

## Developer Tools & Integrations

### Credential Helper — DONE

- Install page at `/install` with shell scripts
- Version API endpoint for automatic updates

### API Documentation — NOT STARTED

- Swagger/OpenAPI specs
- Interactive API explorer
- Code examples, SDKs

### Webhooks — DONE

- Webhook registration UI in settings — `handlers/webhooks.go`, `partials/webhooks_list.html`
- Triggers: `push`, `scan:first`, `scan:all`, `scan:changed`, `quota` (configurable threshold percent) — `pkg/appview/webhooks/`
- HMAC signing, retry with backoff, test delivery, Discord/Slack auto-detection and formatting
- Tier limits: free 1 webhook (`push` + `scan:first`), paid per plan, captain unlimited
- See `docs/WEBHOOKS.md`

**NOT STARTED:**
- Pull-event webhooks (scalability concern, needs batching/throttling — see WEBHOOKS.md)
- Delivery history UI

### CI/CD Integration — PARTIAL

**DONE:**
- Example GitHub Actions and GitLab CI workflows in `examples/plugins/ci-cd/` (signature verification + deploy; reference the unbuilt `atcr-verify` CLI)

**NOT STARTED:**
- Pre-built actions/plugins
- Build status badges

### Infrastructure as Code — PARTIAL

**DONE:**
- Custom UpCloud deployment tool (`deploy/upcloud/`) with Go-based provisioning, cloud-init, systemd, config templates
- Docker Compose for dev and production

**NOT STARTED:**
- Terraform modules
- Helm charts
- Kubernetes manifests (only an example verification webhook exists)
- GitOps integrations (ArgoCD, FluxCD)

---

## Documentation & Onboarding — PARTIAL

**DONE:**
- Install page with credential helper setup
- Learn more page
- Internal developer docs (`docs/`)
- Signup flow: PDS provider picker with curated list, branded OAuth handoff interstitial — `handlers/signup.go`

**NOT STARTED:**
- Interactive onboarding wizard
- Product tour / tooltips
- Help center with FAQs
- Video tutorials
- Comprehensive user-facing documentation site

---

## Advanced ATProto Integration

### Data Export — DONE

- GDPR-compliant data export (`ExportUserDataHandler`)
- Fetches data from AppView DB + all holds where user is member/captain

### Record Viewer — NOT STARTED

- Browse `io.atcr.*` records with raw JSON view
- Record history, diff viewer
- ATP URI links

### PDS Integration — NOT STARTED

- Multi-PDS support, PDS health monitoring
- PDS migration tools
- "Verify on PDS" button

### Federation — NOT STARTED

- Cross-AppView image pulls
- AppView discovery
- Federated search

---

## UI/UX Enhancements

### Theming — PARTIAL

**DONE:**
- Light/dark mode with system preference detection and toggle
- Responsive design (Tailwind/DaisyUI, mobile-friendly)
- PWA manifest with icons (no service worker yet)

**NOT STARTED:**
- Custom themes
- WCAG 2.1 AA accessibility audit
- High contrast mode
- Internationalization (i18n)
- Native mobile apps

### Performance — PARTIAL

**DONE:**
- HTMX lazy loading for data-heavy partials
- Efficient server-side rendering

**NOT STARTED:**
- Service worker for offline caching
- Virtual scrolling for large lists
- GraphQL API
- Real-time WebSocket updates in UI

---

## Enterprise Features — NOT STARTED (except billing)

### Billing — DONE

- Stripe integration (`pkg/billing/`, requires `-tags billing` build tag)
- Checkout sessions, customer portal, subscription webhooks
- Tier upgrades/downgrades

### Everything Else — NOT STARTED

- Organization accounts with SSO (SAML, OIDC)
- RBAC, audit logs for compliance
- SOC 2, HIPAA, GDPR compliance tooling (data export exists, see above)
- Image scanning policy enforcement
- Paid tier SLAs

---

## Miscellaneous Ideas — NOT STARTED

These remain future ideas with no implementation:

- **Image build service** — Cloud-based Dockerfile builds
- **Registry mirroring** — Pull-through cache for Docker Hub, ghcr.io, etc.
- **Deployment tools** — One-click deploy to K8s, ECS, Fly.io
- **Image recommendations** — ML-based "similar images" and "people also pulled"
- **Gamification** — Achievement badges, leaderboards
- **Advanced search** — Semantic/AI-powered search, saved searches

---

## Updated Priority List

**Already done (was "High Priority"):**
1. ~~Multi-architecture image support~~ — display working
2. ~~Vulnerability scanning integration~~ — backend complete
3. ~~Hold management dashboard~~ — implemented on hold admin panel
4. ~~Basic search~~ — working
5. ~~Scan results UI in AppView~~ — badges, CVE details, diff across versions
6. ~~SBOM display UI in AppView~~ — package list, licenses, CSV/SPDX export
7. ~~Webhooks~~ — push/scan/quota triggers, Discord/Slack, tier limits
8. ~~Layer inspection UI~~ (was medium) — layer details + diff on digest page

**Remaining high priority:**
1. Enhanced search (filters, sorting, advanced queries, filter by vuln status)
2. Richer sailor profiles (bio, stats, pinned repos)

**Medium priority:**
1. Pull analytics charts (daily time-series data already collected, needs UI)
2. API documentation (Swagger/OpenAPI)
3. Tag management (promotion, protection, aliases)
4. Onboarding wizard / getting started guide (signup flow exists)
5. Crew invitations (invite by handle, invitation links, self-request flow)

**Low priority / long-term:**
1. Team/organization accounts
2. Image build service
3. Registry mirroring
4. Federation features
5. Internationalization

**Blocked on external dependencies:**
1. Private repositories (requires ATProto private records)
2. Federated timeline (requires ATProto feed infrastructure)

---

**Note:** This is a living document. Features may be added, removed, or reprioritized based on user feedback, technical feasibility, and ATProto ecosystem evolution.

*Last audited: 2026-06-11*