VRDex
VRDex is a VRChat-first scene directory product centered on people, communities, public identity pages, and an opinionated agent-first software-factory workflow.
Repository structure
AGENTS.md - repo-wide agent rules and durable workflow defaultsAGENTS.local.md.example - local operator preference template for AGENTS.local.mdapps/docs - Docusaurus docs site scaffold reading canonical markdown from docs/apps/web - initial Next.js web application scaffoldconvex - Convex backend functions, profile schema, community submissions, and generated API typesdocs/README.md - docs entry pointdocs/planning/ - product, architecture, roadmap, backlog, and issue-planning docsdocs/agentic/ - software-factory, onboarding, and agent workflow docsdocs/backend/ - backend setup notes and implementation-facing docs.opencode/skills/ - repo-local skills, including onboarding
Local bootstrap
- install workspace dependencies:
pnpm install
- install git hooks after dependency changes if needed:
pnpm prepare
- bootstrap an anonymous local Convex deployment and run the backend health query:
pnpm bootstrap:backend:local
- seed the local backend with fake profiles, a world, and events:
pnpm seed:local (it boots and exits its own backend, so run it before the watcher below)
- keep the local Convex backend watcher running:
pnpm dev:backend:local
- run the one-shot local Convex health check alias:
pnpm run:backend:health:local
- typecheck Convex backend files:
pnpm typecheck:backend
- re-run the local backend verification pass:
pnpm verify:backend:local
- confirm committed Convex codegen is current:
pnpm check:backend:generated
- run the web app:
pnpm dev:web
- run the docs site:
pnpm dev:docs
- lint the web app:
pnpm lint:web
- typecheck the web app:
pnpm typecheck:web
- build the web app:
pnpm build:web
- build the docs site:
pnpm build:docs
- run the Vercel web build validation path:
pnpm build:web:vercel
- smoke public routes with Playwright:
pnpm test:e2e
- capture public route screenshots with Playwright:
pnpm test:e2e:visual
- run the baseline local verification pass:
pnpm verify
New here? Read docs/engineering/local-development.md for the full contributor setup, including what needs no credentials and how to add your own Clerk instance.
Convex writes repo-root deployment configuration to .env.local during local setup and keeps anonymous local state under .convex-home/ plus .convex-tmp/. Keep all of those uncommitted. The committed convex/_generated/ files are expected to stay clean after pnpm check:backend:generated.
The local Convex bootstrap now mirrors CONVEX_URL into apps/web/.env.local as NEXT_PUBLIC_CONVEX_URL so the web app can read the placeholder health:status query through the Convex client runtime. If you want the homepage to show live backend data instead of the local configuration fallback, run pnpm bootstrap:backend:local first and keep pnpm dev:backend:local running while you use pnpm dev:web.
The first product schema table is profiles, covering the shared durable record for both people and communities. See docs/backend/profile-schema.md for the current field and state contract.
Profile slug, permission, claim-state, and community-submission contracts live in docs/backend/profile-slugs.md, docs/backend/profile-access-and-claims.md, and docs/backend/community-submissions.md.
Community-submitted public profiles now start at /submit. Person, community,
and world pages render at /<slug>. Community event pages render at
/<community>/events/<event-code>.
Playwright screenshot preview captures desktop and mobile screenshots for public routes and deterministic fixture pages. See docs/testing/playwright-visual-preview.md.
The initial hosted preview path targets Vercel with apps/web as the project root. See docs/deployment/vercel-preview.md; the live deployment identity endpoint is /api/deployment.
The docs site scaffold lives in apps/docs and reads the existing docs/ tree directly. Canonical markdown stays under docs/; the Docusaurus app is the browsable shell.
pnpm verify is the full repo verification pass and now includes the local Convex bootstrap checks. If you are iterating on the web app only, use pnpm verify:web for the lighter web-only path.
Start here
- product/planning context:
docs/planning/README.md
- agentic/software-factory context:
docs/agentic/README.md
- contributor workflow contract:
docs/agentic/contributor-workflow.md
- repo-wide agent defaults:
AGENTS.md
Current direction
Important planning note:
- some items in this repo are still first-pass assumptions
- where a product decision is not locked, it should be treated as a candidate direction to validate in later interviews
Currently locked stack direction:
Next.jsTypeScriptConvexAWSStripeDocusaurusVercel
Currently locked product posture:
- open source
- self-hostable
- public documentation
- public-facing API with clear rate limiting
- infrastructure as code in the repo
Current infrastructure and platform references:
- self-hosting and IaC direction:
docs/developers/self-hosting-and-iac.md
- AWS service baseline:
docs/deployment/aws-baseline.md
- public API posture:
docs/developers/public-api.md
- portable partner-agent guidance:
docs/developers/partner-agent-skill.md
The strongest opening is not another event calendar.
The strongest opening is a canonical public profile layer for VRChat people and communities:
- person profiles for DJs, VJs, hosts, photographers, performers, and scene staff
- community profiles for clubs, VRChat groups, Discord servers, brands, and venues
- community-created entries that can later be claimed by the actual owner
- Discord and VRChat verification so claimed profiles become trusted
- export and integration surfaces for Discord bots, booking tools, and event sites
The product can also act like a VR-native Linktree with richer identity, events, and trust signals.
Current working domain: vrdex.net
Recommended starting point
If you build this as a real product next, the best local references are D:\bench\vrchat-mcp for VRChat integration patterns and D:\bench\vrc-in-world-schedule for simple public endpoints.
Do not depend on VRCTL / vrc.tl access from this environment.
Suggested first build slice
- Public person and community profile pages
- Community submission flow
- Claim profile with Discord OAuth
- Claim profile with VRChat proof code
- Discord bot commands that return profile cards
- Field-level privacy controls and profile customization
- Basic import/export hooks for partners
