+
+ 
+ Try the playground + · + Daily problem +
+ +--- + +## Why dStruct? + +Most coding platforms show you pass/fail. dStruct shows you **what your code is doing** to the underlying data structure. + +- Pick a problem and test case +- Write a solution in the built-in editor +- Run it and scrub through each step with playback controls +- Inspect output and the call stack as execution unfolds + +It is built for learners who want intuition, not just green checkmarks. + ## Features -- **Integrated Code Editor**: Write and visualize LeetCode solutions within the app using the built-in code editor - powered by Monaco Editor. -- **Graphical Visualization**: Gain insights into data structures and algorithms through graphical representations, - making it easier to understand and debug code. -- **Authentication with NextAuth**: Secure user authentication with NextAuth for a personalized experience. -- **Prisma ORM for Database Operations**: Utilizes Prisma ORM for efficient database operations, enhancing data handling - and storage capabilities. -- **GraphQL Integration**: Incorporates GraphQL for efficient query execution and improved API interactions. -- **State Management with Redux Toolkit**: Manages application state seamlessly with the help of Redux Toolkit for - predictable state changes. -- **Internationalization (i18n) Support**: Implements Typesafe i18n for easy translation and localization. -- **Interactive UI with Material-UI and Emotion**: Enhances user interface with the help of Material-UI components and - Emotion for styling. -- **Code Quality and Testing**: Maintains code quality through linting with ESLint, Prettier, and testing with Jest. - -## Tech Stack - -- **Frontend**: - - React - - Next.js - - Redux Toolkit - - Material-UI - - Emotion - - Monaco Editor - - Apollo Client - -- **Backend**: - - Node.js - - Express - - Prisma - - GraphQL - - NextAuth - -- **Database**: - - Prisma ORM - - SQLite (or your preferred database) - -- **Other Tools**: - - Typesafe i18n - - Axios - - Husky (Git Hooks) - - Semantic Release - - Jest Testing Framework - -## 3D Visualization - -This project has a "blender" folder which contains the 3D models used for visualization. The 3D models are created using -Blender and exported as .glb files. -To convert a `.glb` file to a React component, use the `gltffsx` package, for example: +| | | +| ------------------------------ | -------------------------------------------------------------------------------------------- | +| **Interactive visualizations** | 2D and 3D views of trees, graphs, arrays, and other structures that update as your code runs | +| **In-browser code execution** | JavaScript and Python (via Pyodide) — no local interpreter setup required | +| **Monaco editor** | Syntax highlighting, familiar editing experience | +| **Step-by-step playback** | Pause, step forward/back, and adjust speed to follow the algorithm | +| **Curated problems** | Public playground projects with multiple test cases | +| **Daily challenge** | A rotating problem to practice on | +| **Sign in & save progress** | Optional accounts via NextAuth (GitHub, Google) | +| **Multilingual UI** | English plus additional locales via typesafe-i18n | -```bash -pnpm exec gltfjsx blender/logotype/binary_tree.glb -o src/3d-models/BinaryTree.tsx -TtD -``` +## Quick start -## Getting Started +### Prerequisites -1. Clone the repository: +- **Node.js 24** (see `.nvmrc`) +- **pnpm** (`corepack enable`; the repository pins the supported version) +- **PostgreSQL** or **Docker** -``` +### 1. Clone and install + +```bash git clone https://github.com/mkayander/dStruct.git +cd dStruct +cp .env.example .env # edit if needed; placeholders work for basic local dev +pnpm install ``` -2. Install dependencies using pnpm: +### 2. Start PostgreSQL -``` -pnpm install +The quickest option is a local Docker container matching `.env.example`: + +```bash +docker run --name dstruct-postgres \ + -e POSTGRES_USER=dstruct \ + -e POSTGRES_PASSWORD=dstruct \ + -e POSTGRES_DB=dstruct \ + -p 5432:5432 \ + -d postgres:17 ``` -3. Run the development server: +If you already run PostgreSQL, create a `dstruct` role and database (or update +`DATABASE_URL` in `.env` to use your existing credentials). +Then apply the schema and load the public playground problems: + +```bash +pnpm prisma:push +pnpm loadMainDump ``` -pnpm run dev + +### 3. Start the dev server + +```bash +pnpm dev ``` -Visit http://localhost:3000 to access the application. +Open [http://localhost:3000](http://localhost:3000). The playground is at `/playground`. -## Environment Variables +For more detail (Cloud Agent setup, env vars, fonts, dump sync), see **[AGENTS.md](AGENTS.md)**. -Create a .env file in the root directory based on the .env.example file. Fill in the necessary values for the following -variables: +## Environment variables -``` -NODE_ENV=development - -# Prisma -# DEV -DATABASE_URL='mysql://your_dev_database_url' -DIRECT_DATABASE_URL='mysql://your_dev_direct_database_url' - -# PROD -#DATABASE_URL='mysql://your_prod_database_url' -# DIRECT_DATABASE_URL='mysql://your_prod_direct_database_url' - -PRISMA_FIELD_ENCRYPTION_KEY=k1.aesgcm256.your_encryption_key - -# Next Auth -NEXTAUTH_SECRET=your_nextauth_secret -NEXTAUTH_URL=http://localhost:3000 - -# AWS -ACCESS_KEY=your_aws_access_key -SECRET_KEY=your_aws_secret_key -BUCKET_NAME=your_s3_bucket_name -NEXT_PUBLIC_BUCKET_BASE_URL=your_s3_bucket_base_url - -# Verifiable Credentials (VC) REST API -KV_REST_API_READ_ONLY_TOKEN=your_kv_rest_api_read_only_token -KV_REST_API_TOKEN=your_kv_rest_api_token -KV_REST_API_URL=your_kv_rest_api_url -KV_URL=your_kv_url -``` +Copy [`.env.example`](.env.example) to `.env`. For local development you mainly need: + +| Variable | Purpose | +| ----------------------------- | ------------------------------------------ | +| `DATABASE_URL` | PostgreSQL connection string | +| `PRISMA_FIELD_ENCRYPTION_KEY` | Any non-empty string for local dev | +| `NEXTAUTH_SECRET` | Session secret (`openssl rand -base64 32`) | +| `NEXTAUTH_URL` | App URL, e.g. `http://localhost:3000` | -When adding additional env variables, update the schema in /env/schema.mjs accordingly. +OAuth and AWS keys can stay as placeholders unless you are testing those flows. New variables must be added to [`src/env/schema.mjs`](src/env/schema.mjs). ## Scripts -- pnpm build: Build the Next.js application. -- pnpm start: Start the production server. -- pnpm test: Run Jest tests. -- pnpm lint: Lint the code using ESLint. -- pnpm prisma:generate: Generate Prisma client. -- pnpm generate-graphql: Generate GraphQL types. +| Command | Description | +| ---------------------- | -------------------------------------------------- | +| `pnpm dev` | Development server | +| `pnpm build` | Production build | +| `pnpm start` | Run production server | +| `pnpm test` | Vitest + Python harness tests | +| `pnpm lint` | ESLint + TypeScript check | +| `pnpm prisma:push` | Apply Prisma schema to the database | +| `pnpm prisma:generate` | Regenerate Prisma client | +| `pnpm loadMainDump` | Load public problems from `public-dumps/main.json` | +| `pnpm sync-main-dump` | Export public problems from DB to the dump file | + +## Tech stack + +| Layer | Technologies | +| -------------------- | ------------------------------------------------------------------- | +| **App** | [Next.js](https://nextjs.org/) (Pages Router), React 19, TypeScript | +| **UI** | MUI v9, Emotion | +| **State** | Redux Toolkit (UI), TanStack Query via tRPC (server data) | +| **API** | tRPC (primary), GraphQL + Apollo where used | +| **Database** | PostgreSQL, Prisma | +| **Auth** | NextAuth.js | +| **Editor & runtime** | Monaco, Pyodide (Python in the browser) | +| **3D** | Three.js, React Three Fiber | +| **i18n** | typesafe-i18n | +| **Tests** | Vitest, Testing Library | + +Architecture and conventions for contributors live in **[`.cursorrules`](.cursorrules)** and **[`.cursor/rules/`](.cursor/rules/)**. + +## 3D models + +3D assets live under [`blender/`](blender/) and are exported as `.glb` files. To generate a React component from a model: + +```bash +pnpm exec gltfjsx blender/logotype/binary_tree.glb -o src/3d-models/BinaryTree.tsx -TtD +``` -## Contribution Guidelines +## Contributing -Contributions to the project are welcome. Please follow the guidelines outlined in the CONTRIBUTING.md file. +Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a pull request. ## License -This project is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0). +[GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0) — Copyright (c) 2022-present Max Kayander. diff --git a/docs/images/playground-screenshot.png b/docs/images/playground-screenshot.png new file mode 100644 index 00000000..7d167fd0 Binary files /dev/null and b/docs/images/playground-screenshot.png differ
+ 