Find your way around the source

Documentation home · Architecture · Contributing

Devdevian is one repository with a browser application, a shared API and an independently published CLI. The current module layout keeps existing imports and deployment paths stable; this guide is a navigation map, not a second source of configuration.

View source4 min read

Top-level folders#

Location	Purpose
`src/`	React forum, public pages, styles and browser API client
`packages/cli/`	npm package, terminal workspace, commands and its own tests/lockfile
`api/index.mjs`	Vercel entry point for the Express API
`tests/`	Shared server, browser-contract, storage and security regression tests
`scripts/`	Build, migration, operations and isolated verification entry points
`public/`	Publicly served brand assets and product screenshots; never private uploads
`.github/`	CI, issue templates and repository workflows
`docs/`	User, contributor and operator documentation

Server domain modules currently live at the root. Generated dist/, local data, backups, environment files and test artifacts are not source and must stay out of Git.

Start with the behavior you want to change#

Task	Main entry points	Verification
Public landing, FAQ or update history	`src/landing.jsx`, `src/public/`, `scripts/prerender.mjs`	SEO suite and browser checks, including no-JavaScript content
Public conversation URLs, SSR and sitemaps	`public-conversations.mjs`, `conversation-url.mjs`, `src/public/conversation.jsx`	Public access/XSS/API suite and dedicated browser flow
Forum screens, forms or notifications	`src/main.jsx`, `src/forms.jsx`, `src/activity.jsx`	Affected browser flow and mobile layouts
Authentication or provider linking	`auth.mjs`, `oauth-link.mjs`, `password-reset.mjs`, `cli-auth.mjs`	Identity/API suites; real callbacks require provider verification
Posts, replies and accepted answers	`domain.mjs`, `replies.mjs`, `code-reviews.mjs`, `feedback-discussion.mjs`	Permission and feedback regression suites
Personal My work	`my-work.mjs`, `browser`, `terminal loader`, guide	Viewer scopes, parent/task access, current snapshots, local draft/history isolation, browser and PTY
Project participation	`project-access.mjs`, `database barriers`, `browser`, guide	Approval/revocation, private audiences, CAS, legacy writes, recovery, browser and terminal
Project Rooms	`rooms.mjs`, `src/rooms.jsx`, `CLI rooms`, contract	Task races/CAS, private scopes, immutable decision history, encrypted restore, browser/script/PTY
Named reviewers, outcomes and revision links	`review-flow.mjs`, `src/review-flow.jsx`, contract	Role/CAS/private-access tests, restoration, real browser and CLI PTY
Project work and immutable review versions (0.2 branch)	`workspaces.mjs`, `review-revisions.mjs`, contract	Workspace API permissions, migration, recovery and compatibility suite
Community membership and visibility	`spaces.mjs`, `moderation.mjs`	Cross-account public/private access checks
Upload bytes and attachment authorization	`uploads.mjs`, `object-storage.mjs`	Upload tests and isolated S3 fixture
Database/schema or recovery	`database.mjs`, `schema.mjs`, `backup.mjs`	Runtime/recovery suites; explicit migration and restore drill
CLI project Workspaces and review revisions (0.2 branch)	`project-workspace.mjs`, `tui-data.mjs`, CLI guide	Real API browser/CLI continuity, scoped settings, recovery and PTY history/preview/conflict checks
CLI navigation, forms and appearance	`packages/cli/lib/tui.mjs`, `workflow.mjs`, `theme.mjs`	Pure model tests and real pseudo-terminal suites
GitHub context and public PR diffs	`github-context.mjs`, `github-reader.mjs`, `pr-diff.mjs`, `docs/github-pr-reader.md`	Bounded fetch/patch tests and terminal workflows

Boundaries to preserve#

A CLI action and its browser equivalent share server permissions. Do not implement access control only in a component or command.
Public pages render at build time. Do not import server bootstrap, connect to a database or request private API data from them.
Terminal file selection, local drafts and GitHub context are explicit user choices. Do not read or publish an entire working tree implicitly.
Root package.json is the browser/API version; packages/cli/package.json is the npm client version. Record changes in CHANGELOG and, for CLI releases, VERSIONS.
Document non-obvious reasons and invariants in code. Comments should explain access boundaries, lifecycle, compatibility or failure handling rather than repeat syntax.

Read development before running fixtures and reliability before working with migrations or backups. Neither tests nor a configuration check establish that hosted backups or third-party delivery are working.

CLI first-run and diagnostics live in doctor.mjs (bounded, read-only checks), starter-view.mjs (responsive guide), and the command/TUI entry points. Keep reports free of credentials/account data and verify both the pipe-friendly command and real terminal using the doctor suites.

Review workflow: review-queue.mjs defines the authenticated last-visible-speaker predicate reused by post pagination and selected targets. code-reviews.mjs computes disjoint current/earlier totals and filtered target pagination. CLI lib/review-queue.mjs owns the bounded session position cache and query capability check. Queue reads reuse the existing /api/posts visibility boundary.

Owner console and extension trust: platform-owner.mjs (verified server-configured identity), platform-moderation.mjs (public-only console/read scope and extension reports), extension-security.mjs (non-executing static signals), src/platform-moderation.jsx (protected owner UI). Boundary checks live in tests/platform-owner.test.mjs and scripts/platform-owner-browser-check.mjs.