DeWordle

DeWordle is an open-source word game platform migrating to a Soroban-native architecture in the Stellar ecosystem.

• Overview
• Architecture
• Gameplay
• Quick Start
• Docker Compose
• Validation
• Repository Layout
• Documentation
• License

DeWordle is being migrated from a traditional backend-driven architecture toward a Soroban-native design on Stellar.

The current repository contains:

• A Next.js frontend with Stellar wallet integration.
• A NestJS backend providing indexer and read-model infrastructure.
• A Soroban Rust workspace containing the migration-target contracts.
• A TypeScript Soroban SDK consumed by the frontend.
• PostgreSQL-backed projections generated from indexed Soroban events.
• Legacy Cairo contracts retained under onchain/ for reference.

The migration architecture separates on-chain game state and transactions from backend indexing and frontend read models.

flowchart LR
    F[Next.js Frontend] --> W[Stellar Wallet / Soroban SDK]
    W -->|Transactions| C[Soroban Contracts]
    C -->|Events via RPC| I[NestJS Indexer]
    I --> P[(PostgreSQL)]
    I -->|REST Read Models| F

For the detailed migration architecture, see Soroban Foundation Architecture.

The repository includes automated gameplay coverage for the core win flow.

The end-to-end test opens the game, enters the target word, submits the guess, and verifies that the win dialog is displayed.

Gameplay screenshot: Add a real screenshot or GIF from the running application here before closing the README issue.

Once the asset is added, use:

![DeWordle gameplay](./docs/assets/gameplay.png)

Install the frontend dependencies:

npm ci --prefix frontend

Start the Next.js development server:

npm run dev --prefix frontend

The development server runs at http://localhost:3000.

Install the backend dependencies:

npm ci --prefix backend

Start the NestJS development server:

npm run start:dev --prefix backend

Run the Soroban workspace check:

npm run soroban:check

The repository includes a root docker-compose.yml for the local PostgreSQL, Redis, backend, frontend, and Soroban RPC services.

The intended one-line startup command is:

docker compose up --build

Before using it, configure the required environment files for the Compose services. The current Compose configuration references backend/Dockerfile.dev and backend/.env.local; these files are not present in the current repository checkout and should be reconciled before treating the Compose stack as a clean-checkout quickstart.

Run the maintained frontend validation suite:

npm run verify:frontend

Run the maintained backend validation suite:

npm run verify:backend

Validate the Soroban workspace:

npm run soroban:check

.
├── backend/       # NestJS API and indexer
├── frontend/      # Next.js application
├── soroban/       # Soroban Rust workspace
├── onchain/       # Legacy Cairo contracts
├── shared/        # Shared project code
├── infra/         # Infrastructure configuration
├── docs/          # Architecture, development, and contributor documentation
├── e2e/           # End-to-end tests
├── scripts/       # Repository automation and development utilities
├── docker-compose.yml
├── LICENSE
└── package.json

• Repository Surface Map — identifies maintained, transitional, and legacy code paths.
• Soroban Foundation Architecture
• Soroban Local Development
• Frontend Wallet Foundation
• Backend Indexer Foundation
• Environment Configuration
• Wave Issue Candidates
• Wave 5 Execution Plan
• Wave 5 Phases
• Wave 5 Issue Tracks

DeWordle is released under the MIT License.