Skip to content

CLAUDE.md

Latest commit

 

History

History
280 lines (211 loc) · 8.91 KB

CLAUDE.md

File metadata and controls

280 lines (211 loc) · 8.91 KB
Raw

AlianHub Project Management System

Quick reference for development. For detailed guides, see See Also section at the bottom.

What is AlianHub?

AlianHub is a self-hosted, open-source project management system designed for teams needing customization, transparency, and data control without vendor lock-in.

  • Self-hosted: Run on your own servers
  • Highly customizable: Custom fields, templates, workflows
  • Multi-tenant: Single instance serves multiple companies
  • Real-time collaboration: Socket.io LiveSync for instant updates
  • Open-source: AGPL-3.0 licensed, community-driven

Target Users: Enterprises, startups, and teams requiring control, customization, and compliance with data residency requirements.

Quick Start

Install

git clone https://github.com/aliansoftwareteam/AlianHub-Project-Management-System.git
cd AlianHub-Project-Management-System
npm install
cp .env.example .env          # Edit .env with your config
npm run nodemon                # Start dev server on port 4000

First Time?

Visit http://localhost:4000 → Follow installation wizard → Create company & admin user

Required .env

PORT=4000
MONGODB_URL="mongodb://localhost:27017"
JWT_SECRET="your-random-secret-string"
APIURL="http://localhost:4000/"
STORAGE_TYPE="server"         # or "wasabi" for production

See .env.example for complete configuration options.

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│           Web (Vue.js) + Desktop (Electron)             │
└─────────────────────────┬───────────────────────────────┘
                          │
                ┌─────────▼──────────┐
                │  Express API       │
                │  /api/v2/*         │
                │  Socket.io Events  │
                │  JWT Auth          │
                └─────────┬──────────┘
                          │
         ┌────────────────┴────────────────┐
         ▼                                  ▼
      MongoDB                           Storage
      (company-scoped)                  (Wasabi/Local)

Key Principle: All data scoped to companyId for multi-tenancy safety.

Module Organization

Modules are organized by feature, not layer:

Modules/FeatureName/
├── controller/          # HTTP request handlers
├── helpers/             # Business logic
├── routes.js            # Endpoint definitions
└── schema.js            # MongoDB schema (if applicable)

Registration pattern: Each module exports init(app) function in routes.js.

Critical Gotchas ⚠️

1. Always Include companyId in Queries

// ✅ Correct: Company-scoped
MongoDbCrudOpration(companyId, mongoObj, 'findOne');

// ❌ WRONG: Data leak!
Task.findOne({ taskId: 123 });

2. Never Hardcode Collection Names

// ✅ Correct: Use SCHEMA_TYPE enum
{ type: SCHEMA_TYPE.PROJECTS, data: [...] }

// ❌ WRONG: String fails silently
{ type: 'projects', data: [...] }

3. Emit Socket.io Events After Mutations

// ✅ Correct: Broadcast for real-time updates
MongoDbCrudOpration(...).then(result => {
  emitEvent('PROJECT_UPDATED', { projectId: result._id });
  res.json({ status: true, data: result });
});

// ❌ WRONG: Other clients don't see the change
MongoDbCrudOpration(...).then(result => {
  res.json({ status: true, data: result });  // Missing emit
});

4. Clear Cache After Mutations

// ✅ Correct: Remove stale cached data
removeCache(`project:${projectId}`);
removeCache(`projectList:${companyId}`);

// ❌ WRONG: Users see stale data
// (Cache still has old data, no removeCache call)

Tech Stack (Quick Reference)

Backend

  • Express 4.21.2 — HTTP framework
  • MongoDB + Mongoose — Document database (why: flexible schema, nested documents)
  • Socket.io 4.8.1 — Real-time WebSocket events
  • JWT + bcrypt — Stateless authentication
  • Winston — Structured logging
  • Wasabi S3 — File storage (or local filesystem)
  • node-cache — In-memory caching

Frontend

  • Vue.js — Reactive UI
  • Pinia/Vuex — State management
  • Vue Router — Client-side routing
  • vue-i18n — Multi-language support

For detailed rationale, see .claude/TECH-STACK.md.

Common npm Scripts

Command Purpose
npm run nodemon Dev server with hot-reload
npm start Production server
npm run check-version Check app version
cd frontend && npm run build Build Vue.js frontend

File Organization

Folder Purpose
Config/ Configuration (env vars, collections)
Modules/ Feature modules (50+)
frontend/ Vue.js app
common-storage/ File storage abstraction
event/ Socket.io real-time events
middlewares/ Express middleware
utils/ Shared utilities & data files
.claude/ Claude Code documentation

See .claude/FOLDER-STRUCTURE.md for detailed layout.

Code Conventions

Naming

  • Module folders: PascalCase (Modules/Project/)
  • Files: camelCase (getProject.js, routes.js, helper.js)
  • Functions: camelCase (loginAuth(), updateTask())
  • Constants: UPPER_SNAKE_CASE (SCHEMA_TYPE, MAX_FILE_SIZE)
  • API endpoints: kebab-case with version (/api/v2/tasks/create)

Response Format (All Endpoints)

// Success
{ status: true, statusText: "...", data: {...} }

// Error
{ status: false, statusText: "...", message: "..." }

Error Handling Pattern

try {
  // ... logic
} catch (error) {
  req.errorMessageObject = { message: error.message, statusCode: 400 };
  next();  // Passes to error middleware
}

See .claude/CONVENTIONS.md for full naming guide.

Security Essentials

  1. Always scope to companyId — All queries must filter by company
  2. Hash passwords with bcrypt — Never store plain text
  3. Validate input — Check type, length, enum values at API boundary
  4. Use environment variables — Never hardcode secrets
  5. Use HTTPS in production — Protects JWT tokens
  6. Emit after mutations — Socket.io events for real-time sync

See .claude/SECURITY-PATTERNS.md for detailed practices.

See Also

Setup & Installation

  • .claude/SETUP.md — Detailed installation, environment variables, MongoDB setup

Architecture & Design

Development Guides

Best Practices

References & Resources

Historical QA & Audits

Project Stats

  • Tech Stack: Node.js, Express, MongoDB, Socket.io, Vue.js
  • Modules: 50+ feature modules
  • Database: MongoDB (multi-tenant, company-scoped)
  • Authentication: JWT + OAuth (GitHub, Google)
  • Real-time: Socket.io with fallbacks
  • Storage: Wasabi S3 or local filesystem
  • License: AGPL-3.0 (open-source, copyleft)

Quick Links

What Where
Contribute See CONTRIBUTING.md
Security Policy See SECURITY.md
GitHub https://github.com/aliansoftwareteam/AlianHub-Project-Management-System
Issues https://github.com/aliansoftwareteam/AlianHub-Project-Management-System/issues
Docs https://help.alianhub.com

Last Updated: 2026-05-12
Version: 14.0.26
Status: ✅ Documentation reorganized for Claude Code