Skip to main content

Developer Guide for Mixcore

This guide is designed specifically for developers who want to build applications, extend functionality, or contribute to Mixcore.

What You'll Learn​

  • Setting up a development environment
  • Understanding Mixcore's architecture
  • Working with the API
  • Creating custom modules and features
  • Best practices for development

Development Environment Setup​

Prerequisites​

Repository Structure​

Mixcore follows a microservices architecture organized in a monorepo:

mixcore/mix.core/
├─ src/
│  ├─ applications/  # Web applications and APIs
│  ├─ modules/       # Feature modules
│  ├─ platform/      # Core platform services
│  ├─ services/      # Microservices
│  ├─ terraform/     # Infrastructure as code
│  └─ test/          # Test projects
├─ docs/             # Documentation
├─ scripts/          # Utility scripts
├─ k8s/              # Kubernetes configurations
└─ cloud/            # Cloud deployment templates

Quick Start​

The easiest way to set up the development environment:

# Clone the repository with all submodules
git clone --branch develop --recursive https://github.com/mixcore/mix.core.git

# Navigate to the project directory
cd mix.core

# Build and start all services in development mode
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build

This sets up a complete development environment with hot-reload capabilities.

Option 2: Local Development​

For development without Docker:

# Clone the repository
git clone https://github.com/mixcore/mix.core.git

# Navigate to the web application directory
cd mix.core/src/applications/Mix.Cms.Web

# Restore packages and build
dotnet restore
dotnet build

# Run the application in development mode
dotnet run --environment Development

Access the site at https://localhost:5001. For the first time, you'll be redirected to the Setup screen.

Core Architecture​

Mixcore is built with a microservices architecture organized in several key components:

Platform Services​

Located in src/platform/, these services provide the foundation:

  • mix.auth: Authentication and authorization services
  • mix.database: Database abstraction and connection management
  • mix.identity: User identity management
  • mix.service: Core business logic services
  • mix.signalr: Real-time communication
  • mix.storage.lib: Storage abstraction (S3, Azure, local)

Modules​

Located in src/modules/, these are pluggable feature sets that extend functionality:

  • Content management modules
  • E-commerce modules
  • Analytics modules
  • Custom business modules

Applications​

Located in src/applications/, these are the user-facing applications:

  • Mix.Cms.Web: Main CMS web application
  • API gateways
  • Admin portals

Development Workflow​

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes: Implement your feature or fix the bug

  3. Run tests:

    dotnet test src/test

  4. Submit a pull request: Push your branch and create a PR to the develop branch

API Development​

Mixcore follows API-first design principles with both REST and GraphQL endpoints.

REST API​

  • API endpoints are documented using Swagger/OpenAPI
  • Access the API documentation at /swagger when running locally
  • Authentication uses JWT tokens

Example API request with authentication:

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.GetAsync("https://api.example.com/api/v2/posts");
var content = await response.Content.ReadAsStringAsync();

GraphQL​

  • GraphQL schema provides flexible data querying
  • Access the GraphQL playground at /graphql when running locally

Example GraphQL query:

query {
  posts(take: 10, skip: 0) {
    id
    title
    content
    author {
      id
      name
    }
  }
}

Frontend Development​

The admin portal uses modern web technologies:

  • Framework: React with TypeScript
  • State Management: Redux + Redux Toolkit
  • Styling: Styled Components + Material UI
  • Build: Vite

Building the Admin Portal​

# Navigate to the admin portal directory
cd src/applications/Mix.Cms.Admin

# Install dependencies
npm install

# Start development server
npm run dev

Creating Custom Modules​

Mixcore allows developers to create custom modules that extend functionality. A basic module structure includes:

  1. Controller: Handles HTTP requests
  2. Models: Defines data structure
  3. Views: Defines UI components
  4. Services: Implements business logic

For a detailed guide on creating custom modules, see Module Development.

Best Practices​

  • Follow the C# Coding Conventions
  • Write unit tests for all new features
  • Document your code with XML comments
  • Use dependency injection for services
  • Follow the repository pattern for data access
  • Use async/await for all I/O operations

Learn More​

For more detailed information, see these specific developer guides: