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 defaults
• AGENTS.local.md.example - local operator preference template for AGENTS.local.md
• apps/docs - Docusaurus docs site scaffold reading canonical markdown from docs/
• apps/web - initial Next.js web application scaffold
• convex - Convex backend functions, profile schema, community submissions, and generated API types
• docs/README.md - docs entry point
• docs/planning/ - product, architecture, roadmap, backlog, and issue-planning docs
• docs/agentic/ - software-factory, onboarding, and agent workflow docs
• docs/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
• 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

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 server-side Next.js -> Convex baseline now lives at /server-status. It uses fetchQuery from convex/nextjs on a dedicated route rendered dynamically, while the homepage keeps the reactive client-side useQuery path.

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 profile pages render at /p/<slug> and community profile pages render at /c/<slug>.

Playwright screenshot preview captures desktop and mobile screenshots for /, /submit, /server-status, and deterministic public profile fixtures. 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 check page is /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.js
• TypeScript
• Convex
• AWS
• Stripe
• Docusaurus
• Vercel

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

1. Public person and community profile pages
2. Community submission flow
3. Claim profile with Discord OAuth
4. Claim profile with VRChat proof code
5. Discord bot commands that return profile cards
6. Field-level privacy controls and profile customization
7. Basic import/export hooks for partners