AlienCommons

The common land for every TechMC player — a full-stack community platform for publishing, discussion, and discovery.

English | 中文

Overview • Architecture • Tech Stack • Getting Started • Project Structure • Documentation

Overview

AlienCommons is a community platform built for the TechMC Minecraft server. It provides a space for players to publish articles, participate in discussions, manage bookmarks, and engage with content through reactions and comments — all under a unified moderation system.

The project is currently in its early stages, with a production-ready backend and a modern frontend under active development.

Architecture

┌──────────────────────────────────────────────────────┐
│                       Frontend                       │
│           Nuxt 4 · Vue 3 · Tailwind CSS 4            │
│             (Server-Side Rendered SPA)               │
└─────────────────┬────────────────────────────────────┘
                  │ HTTP / WebSocket
┌─────────────────▼────────────────────────────────────┐
│                     Backend API                      │
│           Django 6 · Django REST Framework           │
│            Django Channels · Daphne (ASGI)           │
└────┬────────────┬────────────┬───────────────┬───────┘
     │            │            │               │
┌────▼─────┐ ┌────▼────┐ ┌─────▼─────┐ ┌───────▼───────┐
│PostgreSQL│ │  Redis  │ │    RQ     │ │   AlienMark   │
│    18    │ │    8    │ │  Workers  │ │   (Fastify)   │
└──────────┘ └─────────┘ └───────────┘ └───────────────┘

The backend communicates with an internal AlienMark service (Fastify) for server-side Markdown-to-HTML rendering. Real-time features are powered by Django Channels over WebSockets. Background processing (email, maintenance) runs through RQ task workers backed by Redis.

Tech Stack

• Python 3.14, Django 6, Django REST Framework, Django Channels, Daphne
• PostgreSQL 18, Redis 8, RQ (django-tasks-rq)
• Nuxt 4, Vue 3, TypeScript, Tailwind CSS 4, Pinia
• AlienMark — custom TypeScript Markdown parser, internal Fastify rendering service
• Grafana, Loki, Grafana Alloy
• Docker Compose, Traefik, AWS, Cloudflare DNS
• pnpm workspaces, Turbo, uv, GitHub Actions

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js 24+ and pnpm 11+
• Python 3.14+ and uv

Quick Start

# Clone and install dependencies
git clone https://github.com/LazyAlienServer/alien-commons.git
cd alien-commons
pnpm install

# Start the full development stack
make dev-up

This launches all services: PostgreSQL, Redis, the backend API, task workers, the frontend dev server, AlienMark, and the observability stack (Grafana, Loki, Alloy).

Running Individual Components

# Frontend only
make frontend-dev          # → http://localhost:8080

# Backend tests
make dev-backend-test

# Run all Node checks (lint, typecheck, style)
make node-check

For the full set of available commands, see make/docker.mk and make/node.mk.

Vite+

The frontend toolchain is unified under Vite+ — a single vp CLI that replaces pnpm, Vite, Vitest, and linting commands:

vp dev          # Start the frontend dev server
vp check        # Format, lint, and type-check
vp test         # Run JavaScript tests
vp build        # Build the frontend for production

See the Vite+ Guide for the full list of commands. The project configuration lives in vite.config.ts.

Project Structure

aliencommons/
├── apps/
│   ├── backend/          Django API — articles, posts, comments,
│   │                     bookmarks, reactions, reports, tasks, users
│   ├── frontend/         Nuxt 4 frontend application
│   └── alienmark/        Internal Markdown rendering service (Fastify)
├── packages/
│   └── alienmark/        TypeScript Markdown parser and HTML renderer
├── docs/
│   ├── users/            User guide (EN / 中文)
│   ├── contributors/     Developer documentation
│   └── alienmark/        Markdown engine documentation
├── infra/
│   └── compose/          Docker Compose configurations (dev / stg / pro)
├── o11y/
│   ├── alloy/            Grafana Alloy log collection configs
│   ├── grafana/          Grafana dashboards and provisioning
│   └── loki/             Loki log aggregation configs
├── make/                 Make targets for Docker and Node commands
└── .github/workflows/    CI/CD pipelines

Documentation

Audience	Description	Link
Users	Platform usage guide, community rules	docs/users/
Contributors	Architecture, setup, development workflow	docs/contributors/
AlienMark	Markdown syntax reference and API	docs/alienmark/

All documentation is available in English and Chinese (中文) and built with MkDocs using the Material theme.

Environments

AlienCommons uses three environments:

• dev — local development with Docker Compose
• stg — staging, hosted on AWS, mirrors production as closely as practical
• pro — production, hosted on AWS with Cloudflare DNS for aliencommons.com