Reference Designs & Design Community

Reference Designs is a two-sided feature: a private library inside your organization for the design patterns your team reuses, and a public Design Community website where moderated designs from any organization can be discovered, viewed, and downloaded by anyone (no login required).

The point is to capture the institutional knowledge that usually lives in one engineer's head - the "we always lay out the power stage this way", "this 4G antenna pattern works, this one does not" - and make it searchable across teams. When a design is good enough to share, an organization can submit it for public review; once a super-admin approves it, it appears on the Design Community website.

---

Two surfaces, one collection

Visibility is a per-reference setting. You can keep a design private forever, or flip it to public when you are ready for review.

---

Concepts

---

Quick start (5 minutes)

1. Create a private reference

1. From the sidebar, click Reference Designs (top-level)
2. Click New reference
3. Fill in:

- Title (e.g. "Low-noise LDO layout pattern for 4G modules") - Description (a paragraph or two; what problem it solves and when to use it) - Content (optional long-form notes, design rules, gotchas) - Category (e.g. power_pattern) - Tags (free-form, up to 20) - Compatibility (optional, e.g. "BG95-M3, SIM7600") - Visibility: leave as Private for now

1. Save. The reference appears in your library with status draft.

2. Add attachments

1. Open the reference detail
2. Click Upload attachment
3. Select a file (PDF, schematic, layout, BOM, image - anything)
4. The upload is recorded with original filename, size, and mime type. Multiple attachments per reference are supported.

Note: If a reference is currently published and you upload a new attachment, the reference re-enters the moderation queue. Edits to published references re-trigger review by design.

3. Submit for public review

1. Open the reference detail
2. Change Visibility to Public (or use the Submit for review button if it is a draft)
3. The reference's status flips to pending_review. A super-admin will see it in the review queue.
4. While pending, you can still edit; further edits keep status as pending.

4. After approval

• The reference appears on the public Design Community website at /design-community
• Anyone can browse, search, and download attachments without logging in
• The owning org keeps full control: edit again to push a new version back through review, or flip back to private to remove it from the public site

5. If rejected

• The super-admin sets status to rejected and writes a reason
• The reason appears on your reference detail (visible to your org only)
• Fix the feedback, then re-submit via the Submit for review button

---

Workflow: super-admin moderation

(Super-admin only. Org-admin users cannot moderate - cross-tenant control lives at the super-admin level only.)

1. Open /admin/references in the dashboard
2. The queue defaults to pending_review, sorted by submission time
3. Click any entry to inspect: title, description, full content, attachments, publisher org
4. Approve: optionally mark Verified (badge on public site), then click Approve. The reference becomes published and shows up on the Design Community site.
5. Reject: enter a reason (required, max 500 chars), then click Reject. The reference goes back to the publisher with the reason visible.

Every approve / reject writes an audit row (reference_admin_approved, reference_admin_rejected) attributed to the super-admin, scoped to the publisher's organization for tenancy-correct audit queries.

---

Workflow: public Design Community site

The public site is no-login. URLs:

• /design-community - browse all published references, search, filter by category, toggle "verified only"
• /design-community/[refId] - reference detail with attachments, view count, download count
• Downloads bump the per-reference download counter via a signed-URL endpoint (or local-served path on dev)

This is intentionally public, intentionally searchable, intentionally crawlable. The point is reach: surface a good design pattern to engineers who do not yet have an S3Suite account.

---

Reference

Permissions

• Create / edit / delete / submit on your own references: project writer roles in the owning org
• Approve / reject: super-admin only. Org-admin users are explicitly blocked from cross-tenant moderation.
• Read public references: anyone (no auth)

Editing a published reference

• A content edit (title, description, content) or any attachment change on a published reference flips its status back to pending_review
• The verified badge is dropped on edit; a fresh moderation pass can re-apply it
• The public site continues to show the last published version until the new version is approved; if rejected, the prior published version stays live

Cannot delete a published reference

• Public published references cannot be deleted directly. Flip visibility to private first (drops it from the public site), then delete.
• Audit trail is intentional. The public site has stable URLs.

Attachment storage

• Attachments go through the storage service (S3 in production, local disk in dev)
• Public downloads return a signed URL valid for 1 hour (S3) or a relative path (local)
• The download endpoint atomically increments downloadCount without blocking the redirect

Module gate

• Reference Designs is not gated by any module. It is available organization-wide as soon as the org exists.

Audit log

• Every mutation writes a logAudit row: reference_created, reference_updated, reference_deleted, reference_submitted_for_review, reference_attachment_uploaded, reference_attachment_removed, reference_admin_approved, reference_admin_rejected

Common pitfalls

• "I cannot approve my org's submission." Correct, only super-admin can approve. This stops org-admin users from cross-promoting their own designs.
• "I uploaded a new attachment and my published reference disappeared from the public site." It is back in pending_review. A super-admin will look at it; the prior version stayed live until then.
• "Delete is greyed out." The reference is published-public. Flip to private first.
• "Cannot submit, error says title is required." Validation rejects on the server too; the backend returns details: string[] that the UI surfaces inline.

---

Related docs

• Knowledge Base and Diary - internal write-ups; complementary to references
• Engineering Suite - design files live here; references are the curated, shareable subset
• Roles and Permissions - who can publish, who can moderate
• Security and Access - org scoping, super-admin boundaries, public surface