Set up core project structure with module boundaries

Oct 13, 2025 by wbrum.org 101 views

Core Technical Validation Requirement

Implementing a foundational project architecture that enables rapid iteration on our era-transition prototype while maintaining clean separation of concerns is crucial. This issue validates our ability to integrate React, THREE.js, and MobX in a performant configuration.

Implementation Approach

To achieve this, we will follow a structured approach:

Set up core project structure with module boundaries: Establish a clear and maintainable project structure that enforces strict boundaries between different components and modules.
Configure Webpack/Vite for optimal THREE.js integration: Optimize the build process to ensure seamless integration of React and THREE.js.
Establish state management patterns for era-specific data: Implement a robust state management system using MobX to handle era-specific data.

Implementation Details

// Project structure (enforce strict boundaries)
/src
  /components      // React view layer
    /ui            // Pure UI components (menus, controls)
    /game          // Game-specific components
    /shared        // Cross-cutting component utilities
  /state           // MobX state management
    gameState.ts   // Core game state
    buildingState.ts // Building management
  /three           // THREE.js integration layer
    /renderers     // Custom renderer implementations
    /loaders       // Asset loading utilities
  /workers         // Web Workers for computation offloading
  /utils           // Pure utility functions

Core Architecture Implementation

We will focus on establishing the rendering pipeline with React Three Fiber:

// src/components/game/GameWorld.tsx
import React from 'react';
import { Canvas } from '@react-three/fiber';
import { observer } from 'mobx-react-lite';
import { GameScene } from './GameScene';
import { useStore } from '../../state/RootStore';

export const GameWorld = observer(() => {
  const { gameState } = useStore();
  
  return (
    <Canvas
      shadows
      camera={{ position: [50, 50, 50], fov: 45 }}
      onCreated={({ gl }) => {
        gl.setClearColor('#1a1a2e');
        gl.physicallyCorrectLights = true;
      }}
    >
      <ambientLight intensity={0.4} />
      <directionalLight 
        position={[100, 100, 100]} 
        intensity={0.8} 
        castShadow 
      />
      <GameScene 
        era={gameState.currentEra} 
        eraProgress={gameState.eraProgress} 
      />
    </Canvas>
  );
});

Core State Management Implementation

We will implement the foundation of our reactive state architecture:

// src/state/RootStore.ts
import { createContext, useContext } from 'react';
import { GameState } from './GameState';
import { BuildingState } from './BuildingState';
import { ResourceState } from './ResourceState';

export class RootStore {
  gameState: GameState;
  buildingState: BuildingState;
  resourceState: ResourceState;
  
  constructor() {
    this.gameState = new GameState(this);
    this.buildingState = new BuildingState(this);
    this.resourceState = new ResourceState(this);
  }
}

// Create store context
const StoreContext = createContext<RootStore>(null!);

// Create provider component
export const StoreProvider = ({ children }: { children: React.ReactNode }) => {
  const store = new RootStore();
  return (
    <StoreContext.Provider value={store}>
      {children}
    </StoreContext.Provider>
  );
};

// Hook for accessing store
export const useStore = () => useContext(StoreContext);

Performance Optimizations

To ensure optimal performance, we will implement the following optimizations:

Implement React.memo() with careful dependency tracking for rendering-intensive components: This will help prevent unnecessary re-renders and improve performance.
Configure MobX for optimal re-rendering patterns: We will configure MobX to minimize unnecessary re-renders and improve performance.
Set up skeleton for Web Worker offloading: We will set up a basic Web Worker offloading system to offload computationally intensive tasks and improve performance.

Acceptance Criteria

To ensure that our implementation meets the requirements, we will test the following acceptance criteria:

Project successfully builds and runs with React + THREE.js integration: We will verify that the project builds and runs without errors.
State changes trigger appropriate re-renders with minimal performance impact: We will test that state changes trigger the correct re-renders and do not have a significant performance impact.
Directory structure enforces clear architectural boundaries: We will verify that the directory structure enforces clear architectural boundaries and is maintainable.
Basic scene renders with proper lighting and camera setup: We will test that the basic scene renders with proper lighting and camera setup.
Q&A: Initializing Core React-THREE.js Architecture with MobX State Integration ================================================================================

Frequently Asked Questions

We've received several questions about initializing the core React-THREE.js architecture with MobX state integration. Here are some of the most frequently asked questions and their answers:

Q: What is the purpose of using MobX for state management in this project?

A: MobX is a popular state management library that helps manage complex state changes in a reactive way. In this project, we're using MobX to manage era-specific data and ensure that the state changes trigger the correct re-renders.

Q: How do I set up the project structure with module boundaries?

A: To set up the project structure with module boundaries, create a new directory for the project and create the following subdirectories:

/components: for React view layer components
/state: for MobX state management
/three: for THREE.js integration layer
/workers: for Web Workers for computation offloading
/utils: for pure utility functions

Q: How do I configure Webpack/Vite for optimal THREE.js integration?

A: To configure Webpack/Vite for optimal THREE.js integration, you'll need to install the necessary dependencies and configure the build process to include the THREE.js library. You can refer to the official documentation for more information.

Q: How do I implement React.memo() with careful dependency tracking for rendering-intensive components?

A: To implement React.memo() with careful dependency tracking for rendering-intensive components, you'll need to use the React.memo() function and pass the correct dependencies to it. This will help prevent unnecessary re-renders and improve performance.

Q: How do I configure MobX for optimal re-rendering patterns?

A: To configure MobX for optimal re-rendering patterns, you'll need to use the @observer decorator and configure the MobX store to minimize unnecessary re-renders. You can refer to the official documentation for more information.

Q: How do I set up a skeleton for Web Worker offloading?

A: To set up a skeleton for Web Worker offloading, you'll need to create a new directory for the Web Workers and create a basic Web Worker script that can offload computationally intensive tasks. You can refer to the official documentation for more information.

Q: What are the acceptance criteria for this project?

A: The acceptance criteria for this project are:

Project successfully builds and runs with React + THREE.js integration
State changes trigger appropriate re-renders with minimal performance impact
Directory structure enforces clear architectural boundaries
Basic scene renders with proper lighting and camera setup

Additional Resources

If you have any additional questions or need further clarification on any of the topics covered in this article, please refer to the following resources:

Official React documentation: https://reactjs.org/
Official THREE.js documentation: https://threejs.org/
Official MobX documentation: https://mobx.js.org/
Official Webpack documentation: https://webpack.js.org/
Official Vite documentation: https://vitejs.dev/