Application Scaffolding - acdc-digital/soloist_pro GitHub Wiki

graph TD
  root["soloist_pro-monorepo"]
  root --> convex["convex/"]
  root --> electron["electron/"]
  root --> renderer["renderer/"]
  root --> website["website/"]

1. Monorepo Root

   • Workspace Declaration
     Hosts pnpm-workspace.yaml, which registers the four primary workspaces (convex, electron, renderer, website).
   • Shared Scripts & Dependencies
     The root package.json defines shared development scripts (dev:convex, dev:renderer, dev:electron, dev:website), hoists the convex SDK as a dependency, and centralizes linting via Trunk.
   • Global Configuration
     Files like trunk.yaml and .gitignore live at the root to enforce consistent lint rules and ignore patterns across all sub-projects.

2. convex/

   • Backend Definition
     Contains Convex schema definitions (schema.ts), and query/mutation handlers (logs.ts, forecasts.ts).
   • Configuration
     convex.json points at "functions": ".", and .env.local holds CONVEX_DEPLOYMENT and CONVEX_URL for seamless local development (pnpm run dev:convex).
   • Modern API
     Upgraded to Convex v1.x, enabling streamlined imports (defineSchema, defineTable, v).

3. electron/

   • Desktop Shell
     Houses main.js, which creates an Electron BrowserWindow pointing to http://localhost:3000 in development or bundled renderer assets in production.
   • Dependency & Scripts
     The workspace’s package.json declares electron as a dependency and provides the dev script (electron .) for rapid iteration.

4. renderer/

   • Next.js Application
     A standalone Next.js 15 app that powers the core UI, rendered inside the Electron shell. Supports the App Router or Pages Router pattern as configured.
   • Project Structure
     Organized into src/app/ (or pages/), with supporting directories for lib/, hooks/, and store/ (Zustand).
   • Data Integration
     Imports Convex bindings from convex/_generated/api.ts and leverages useQuery / useMutation for real-time data flows.

5. website/

   • Marketing & Signup
     A separate Next.js project dedicated to public-facing landing pages, pricing, and signup flows.
   • Port Isolation
     Runs on its own port (e.g., 3002) to prevent conflicts with the renderer’s dev server.
   • Content & Components
     Static assets in public/, marketing pages in pages/, and reusable UI components under components/.

• Isolation & Sharing
  Each workspace maintains its own dependencies, build scripts, and configuration, yet shares core libraries (e.g., the Convex SDK) through root-level hoisting.

• Consistent Tooling
  Trunk enforces a unified linting strategy (pnpm run lint), and TypeScript checks are centralized (pnpm run typecheck).

• Streamlined Development
  Four intuitive root commands (pnpm run dev:<workspace>) spin up each service independently—no more context-switching or manual port management.

• Scalability & Maintenance
  Adding features follows a repeatable pattern: introduce new files or folders in the appropriate workspace, update its package.json if needed, and the monorepo tooling handles the rest.

This scaffolding strikes a balance between modularity and cohesion, enabling efficient development, smooth CI/CD pipelines, and simplified cross-workspace refactoring.