Project Structure - RumenDamyanov/js-chess GitHub Wiki

Project Structure

Understanding how the JS Chess Frontend Showcase is organized will help you navigate and contribute to the project effectively.

Repository Overview

js-chess/
├── 📄 README.md                  # Main project documentation
├── 📄 LICENSE.md                 # MIT License
├── 📄 CONTRIBUTING.md            # Contribution guidelines
├── 📄 SECURITY.md                # Security policy
├── 📄 FUNDING.md                 # Support information
├── 📄 CHANGELOG.md               # Version history
├── 🐳 docker-compose.yml         # Multi-container orchestration
├── 🔧 Makefile                   # Build automation
├── 🔒 .env.example               # Environment template
├── 🚫 .gitignore                 # Git ignore rules
├── 📦 .gitmodules                # Git submodule config
├── 📂 apps/                      # Frontend applications
├── 📂 backend/                   # Backend API (submodule)
├── 📂 shared/                    # Shared resources
├── 📂 docs/                      # Documentation
├── 📂 scripts/                   # Build scripts
├── 📂 wiki/                      # Wiki documentation
└── 📂 assets/                    # Common assets

Frontend Applications (apps/)

Each framework implementation is completely self-contained:

Vanilla JavaScript (apps/vanilla-js/)

vanilla-js/
├── index.html              # Main HTML file
├── js/
│   └── chess-game.js       # Main game logic
├── css/
│   └── style.css          # Styling
├── nginx.conf             # Nginx configuration
├── Dockerfile             # Container definition
└── README.md              # Framework-specific docs

jQuery (apps/jquery/)

jquery/
├── index.html              # HTML with jQuery integration
├── js/
│   └── chess-game.js       # jQuery-based implementation
├── css/
│   └── style.css          # jQuery-specific styling
├── nginx.conf             # Nginx configuration
├── Dockerfile             # Container definition
└── README.md              # Documentation

Vue.js (apps/vue-js/)

vue-js/
├── index.html              # Entry point
├── package.json            # Dependencies
├── vite.config.js          # Build configuration
├── src/
│   ├── main.js            # Vue app entry
│   ├── App.vue            # Root component
│   ├── components/        # Vue components
│   ├── services/          # API services
│   └── styles/            # Component styles
├── public/                # Static assets
├── nginx.conf             # Production server config
├── Dockerfile             # Multi-stage build
└── README.md              # Vue-specific documentation

React.js (apps/react-js/)

react-js/
├── index.html              # React entry point
├── package.json            # Dependencies
├── vite.config.js          # Vite configuration
├── src/
│   ├── main.jsx           # React app entry
│   ├── App.jsx            # Root component
│   ├── components/        # React components
│   ├── hooks/             # Custom hooks
│   ├── services/          # API integration
│   └── styles/            # Component CSS
├── nginx.conf             # Nginx config
├── Dockerfile             # Production build
└── README.md              # React documentation

Angular (apps/angular/)

angular/
├── angular.json            # Angular workspace config
├── package.json            # Dependencies
├── tsconfig.json          # TypeScript config
├── src/
│   ├── main.ts            # Bootstrap file
│   ├── index.html         # Main HTML
│   ├── styles.css         # Global styles
│   └── app/
│       ├── app.component.ts    # Root component
│       ├── components/         # Feature components
│       └── services/           # Angular services
├── nginx.conf             # Production server
├── Dockerfile             # Multi-stage build
└── README.md              # Angular documentation

Landing Page (apps/landing/)

landing/
├── index.html              # Project showcase
├── css/
│   └── landing.css        # Landing page styles
├── js/
│   └── landing.js         # Interactive features
├── nginx.conf             # Static file serving
├── Dockerfile             # Simple container
└── README.md              # Landing page docs

Backend API (backend/)

The backend is included as a git submodule pointing to the go-chess repository:

backend/
└── go-chess/               # Git submodule
    ├── main.go            # Server entry point
    ├── api/               # HTTP handlers
    ├── engine/            # Chess game engine
    ├── ai/                # AI implementations
    ├── Dockerfile         # Backend container
    └── go.mod             # Go dependencies

Shared Resources (shared/)

Common code and assets used across multiple frameworks:

shared/
├── api/                    # API client libraries
│   ├── chess-api.js       # JavaScript client
│   ├── chess-api.ts       # TypeScript client
│   └── websocket-client.js # WebSocket handling
├── styles/                # Common CSS
│   ├── common.css         # Base styles
│   ├── header.css         # Navigation headers
│   └── chess-board.css    # Board styling
└── assets/                # Static assets
    ├── pieces/            # Chess piece images
    ├── sounds/            # Game sounds
    └── icons/             # UI icons

Documentation (docs/)

Detailed guides and documentation:

docs/
├── api-integration.md      # API usage guide
├── development.md         # Development setup
├── deployment.md          # Production deployment
└── castling-implementation.md # Chess rules

Scripts (scripts/)

Automation and convenience scripts:

scripts/
├── build-all.sh           # Build all containers
├── start-dev.sh           # Development startup
├── setup-dev.sh           # Initial setup
└── setup-simple.sh        # Minimal setup

Wiki (wiki/)

Comprehensive documentation (GitHub Wiki source):

wiki/
├── Home.md                # Wiki homepage
├── Quick-Start.md         # Getting started
├── Project-Structure.md   # This file
├── [Framework]-Guide.md   # Framework-specific guides
└── [Topic].md             # Various topic guides

Key Files Explained

docker-compose.yml

Orchestrates all containers:

  • chess-backend: Go API server
  • chess-landing: Project showcase (port 3000)
  • chess-vanilla: Vanilla JS app (port 3001)
  • chess-jquery: jQuery app (port 3002)
  • chess-vue: Vue.js app (port 3003)
  • chess-react: React app (port 3004)
  • chess-angular: Angular app (port 3005)

Makefile

Provides convenient commands:

  • Build, start, stop, restart containers
  • Individual service management
  • Development utilities
  • Cleanup operations

.gitmodules

Defines the backend submodule:

[submodule "backend/go-chess"]
    path = backend/go-chess
    url = https://github.com/RumenDamyanov/go-chess.git

Development Workflow

  1. Clone with submodules: git clone --recursive
  2. Start services: make up or docker-compose up
  3. Make changes to any framework in apps/
  4. Test changes using individual container restarts
  5. Add documentation to appropriate wiki/ files

Framework Isolation

Each framework implementation is:

  • Self-contained: All dependencies in its own directory
  • Containerized: Separate Docker container
  • Port-isolated: Different port for each app
  • Build-independent: Can be built and deployed separately

This allows for:

  • Independent development and testing
  • Framework-specific optimizations
  • Easy comparison between implementations
  • Modular deployment options

Adding New Frameworks

To add a new framework:

  1. Create new directory in apps/
  2. Implement the chess application
  3. Add Dockerfile and nginx.conf
  4. Update docker-compose.yml
  5. Add Makefile targets
  6. Create framework guide in wiki/

See Adding New Frameworks for detailed steps.

Understanding the Code Flow

  1. Frontend makes API calls to backend
  2. Backend processes chess moves and AI requests
  3. WebSocket provides real-time updates
  4. Shared CSS ensures consistent styling
  5. Docker handles all the infrastructure

This structure makes it easy to focus on framework-specific implementations while maintaining consistency across the entire showcase.