Repository navigation
Conversation
…rts page Two issues found reviewing the docs against actual source (magistrala, atom, magistrala-ui repos): - api.mdx: the Channels callout claimed there is "no direct equivalent" for enabling/disabling a channel. False — magistrala-ui's Enable/Disable toggle works today via updateResource setting attributes.status. Fixed the callout to describe that convention accurately, including the important caveat that Atom's authorization checks don't read this flag, so a "disabled" channel still accepts traffic under a live Permission Block. Connect/Disconnect explanation in the same callout was already accurate and is unchanged. - certs.mdx: rewritten entirely. The page documented cli/certs.go commands against a `certs` REST service and OpenBao/Vault PKI mode that no longer exist anywhere (no docker service, no OpenBao references in Atom's source) — certs are now issued through Atom's GraphQL API natively (issueGeneratedCertificateV2, issueCertificateFromCsrV2, renew/revoke mutations, certificates/certificate queries) with CA/CRL/OCSP served as plain HTTPS routes on Atom itself. Verified the trust-bundle route live against a local Atom instance (200 OK). Fixed the one resulting dangling anchor link in edge.mdx.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
magistrala-docs | f92ddf9 | Commit Preview URL Branch Preview URL |
Sep 10 2026, 02:58 PM |
…ied pass Ran every doc page through a systematic verification against the real source (magistrala, atom, magistrala-ui, magistrala-ee repos) rather than just the pages a teammate had already flagged. Found and fixed: - cli/authz-cli.mdx: example response used "authorized" instead of the schema's real "allowed" field; example used --object-kind channel instead of the real value, "resource" (channel is an ObjectType, not an ObjectKind). - cli/introduction-to-cli.mdx: reconstructed --help output was missing the password and users commands; showed a nonexistent -d shorthand for --graphql-url; falsely claimed the repo doesn't build cleanly; missing a Users CLI link in "See also". - entities.mdx: Channels were described as atom.Entity sharing the same Go struct as Devices — they're actually a separate type, atom.Resource, with no Status/ExternalID/DeviceTypeID fields. Split into two sections. Also dropped a stale "no users CLI command" line, and removed an entirely fabricated "Tags Filtering" section describing a tags query parameter and REST-style filter syntax that doesn't exist anywhere in Atom's GraphQL schema. - authorization.mdx: ScopeMode enum list was missing "Platform" and included a fabricated "an object group itself" value that isn't a real variant. - services/consumers.mdx: example imports used wrong Go package paths (consumers/timescale, consumers/postgres) that don't exist — real paths are consumers/writers/timescale, consumers/writers/postgres. - services/readers.mdx: both API examples used port 8000, which neither reader defaults to (postgres-reader is 9009, timescale-reader is 8180). - dev-tools/events.mdx: clarified that no current service publishes to Redis Streams (the implementing package has zero importers anywhere) rather than grouping the historical mqtt-adapter mention loosely with services that later moved into Atom. - architecture.mdx, storage-architecture.mdx: removed a "NATS available as a build-time alternative" claim that isn't true — there are zero NATS references anywhere in the current magistrala repo. Also fixed a fabricated attributes.magistrala nested JSONB structure (the real attributes are flat top-level keys) and added a missing device_id column to the messages hypertable schema example.
… type name Verified the three remaining EE service pages (alarms.mdx, reports.mdx, rules-engine.mdx) against magistrala-ee source. alarms.mdx checked out fully accurate (~40 claims). Fixed what didn't: - reports.mdx: every API example (18 occurrences) used port 9008, which is the Rules Engine's port — the real Reports service port is 9017 (cmd/reports/main.go). - reports.mdx: the "Metric Structure" section showed the response-side Metric struct (singular DeviceID) without noting that the request body for creating/updating a report config actually takes ReqMetric, whose DeviceIDs field is a []string. Added the ReqMetric shape and fixed the Create Report Configuration example's payload (device_id -> device_ids array) to match, since as written it used a field that doesn't exist on the real request type. - reports.mdx: MetricConfig is missing a Title field in both the earlier struct listing and the same Create Report Configuration example -- Title is mandatory (MetricConfig.Validate() rejects an empty one) and the example would be rejected by the real API as written. - reports.mdx: EmailSetting struct block was missing the Content field, inconsistent with the field table directly below it and the real struct. - reports.mdx: fixed a genuine JSON syntax error (missing comma) in the Create Report Configuration example, and a markdown bug where the MetricConfig/AggConfig Go structs and the field table between them were stuck inside one unclosed code fence, so the table never rendered as a table. - rules-engine.mdx: the alarms output's example struct was named Alarms (real name: Alarm, singular) and showed a literal Type field that doesn't exist on the struct -- the "type" key on the wire comes from a custom MarshalJSON. Low impact: the JSON output shape shown elsewhere on the page was already correct.
…rent fact NATS was never a real feature here (unlike SpiceDB/old-CLI, which genuinely existed and got replaced) -- it was fabricated from the start. Explaining its absence in architecture.mdx repeats the exact anti-pattern this whole cleanup effort set out to remove: dwelling on what isn't there instead of just stating what is. A reader has no reason to expect a NATS alternative unless the docs tell them to.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two inaccuracies found while reviewing the docs against actual source (magistrala, atom, magistrala-ui repos), reported by a teammate:
magistrala-ui's Enable/Disable toggle works today viaupdateResourcesettingattributes.status. Rewrote the callout to describe that convention accurately, including the caveat that Atom's authorization checks don't read this flag (a "disabled" channel still accepts traffic under a live Permission Block). The Connect/Disconnect explanation in the same callout was already accurate and is unchanged.cli/certs.gocommands against acertsREST service and OpenBao/Vault PKI mode that no longer exist anywhere — certs are now issued through Atom's GraphQL API natively (issueGeneratedCertificateV2,issueCertificateFromCsrV2, renew/revoke mutations,certificates/certificatequeries), with CA/CRL/OCSP served as plain HTTPS routes on Atom itself. Fixed the resulting dangling anchor link inedge.mdx.Follow-up: given those two findings, did a full systematic pass over the rest of the dev-guide docs — every mutation/query name, CLI command, env var, port number, and Go import path checked against the real source (
magistrala,atom,magistrala-ui,magistrala-eerepos), not just the pages already flagged. Found and fixed 21 more confirmed-wrong claims across 11 files:cli/authz-cli.mdx: wrong response field (authorized→allowed) and wrong--object-kindexample value (channel→resource).cli/introduction-to-cli.mdx: reconstructed--helpoutput was missing thepassword/userscommands, showed a nonexistent-dshorthand, falsely claimed the repo doesn't build, and was missing a Users CLI link.entities.mdx: Channels were wrongly described as sharing theatom.EntityGo type with Devices — they're a separate type,atom.Resource. Split into two sections, fixed a stale "no users CLI" line, and removed an entirely fabricated "Tags Filtering" section (REST-style query syntax that doesn't exist in Atom's GraphQL schema).authorization.mdx:ScopeModeenum list was missingPlatformand included a fabricated value that isn't real.services/consumers.mdx: example Go imports used nonexistent package paths.services/readers.mdx: both API examples used the wrong port (neither reader defaults to 8000).dev-tools/events.mdx: corrected a claim that the (nonexistent) mqtt adapter currently publishes to Redis Streams.architecture.mdx,storage-architecture.mdx: removed a fabricated "NATS available as a build-time alternative" claim (zero NATS references anywhere in the repo), a fabricated nestedattributes.magistralaJSONB structure (real attributes are flat), and added a missingdevice_idcolumn to a schema example.services/reports.mdx: every API example (18 occurrences) used the Rules Engine's port instead of the Reports service's real port (9017); the create-config example used a request field that doesn't exist on the real request type and was missing a mandatorytitlefield it would be rejected without; fixed a genuine JSON syntax error and a markdown bug where a table was stuck inside an unclosed code fence.services/rules-engine.mdx: an example struct was misnamed and showed a field that doesn't exist on the real type (the JSON output shown elsewhere on the page was already correct).services/alarms.mdxwas also checked and found fully accurate — no changes needed there.Test plan
pkg/atomGo client,cli/*.go,magistrala-ui's GraphQL calls,magistrala-ee's edition limits and service structs — grepped directly, not from memory/certs/trust-bundle.pemreturns 200 against a local Atom instancereports.mdxactually parsespnpm run lintpassespnpm run types:check(fumadocs-mdx + next typegen + tsc --noEmit) passes