tiag0ss/myelin repository overview

⁠Myelin

Myelin is a full-stack, self-hosted project and delivery platform with task tracking, resource planning, time tracking, and multi-tenant organization support.

Version 1.0 — production-ready core (projects, planning, time, tickets, reporting, integrations). Report bugs and feature requests on GitHub.

⁠Features

• 📋 Project & Task Management — Kanban boards, Gantt view, task hierarchy (parent/subtasks), dependencies, custom statuses/priorities/types with Lucide icons, and quick navigation between tasks and projects
• 📊 Resource Planning — Gantt chart with drag-and-drop allocation, user availability tracking, intelligent replanning, recurring blocks, Outlook calendar overlay (loads in background), and split planning
• ⏱️ Time Tracking — Daily and weekly timesheet views, per-task time entries, timers, CSV export
• ✅ Approvals Center — Team-lead/admin approval flows for time entries, vacations, and expenses (partial reimbursement supported)
• 🏖️ Vacations & Holidays — Annual vacation management, out-of-office requests, non-working-day-aware requests, and country holiday calendars
• 👥 Multi-Tenant Organizations — Multiple organizations, team management, permission groups
• 🔐 Role-Based Permissions — Developer, Support, Manager roles with granular permission control
• 🎫 Ticket System — Support ticket management with auto-numbering, auto-assignment, task conversion, Jira integration, and per-organization statuses/priorities
• 🌐 Customer Portal — Customer-facing overview with ticket/project visibility and constrained ticket creation
• 👤 Customer Management — Customer database with organization associations and default support user assignment
• 📞 Call Records — Structured call logging with time, participants, notes, and optional task/project linkage
• 🛠️ Application Lifecycle Management — Application registry, version control, release management with PDF exports, task-to-release linking
• 🔗 Integrations — Jira, GitHub, Gitea, and Outlook calendar (Microsoft Graph); credentials encrypted at rest
• 📬 Outlook Email Task Queue — Route emails via Cloudflare Email Routing to a per-user queue; import as tasks from the project UI (setup guide⁠)
• 🔑 API Tokens — Personal pt_... tokens for webhooks, Workers, and integrations (Profile → API Tokens)
• 📝 Rich Text Editor — Tiptap-based editor with formatting; images upload to /uploads/editor (URL references; base64 fallback only if upload is unavailable)
• 📔 Memos System — Calendar-based notes with visibility controls (Private, Organizations, Public), tags, and rich content
• 🔄 Recurring Tasks — Outlook-style recurring time blocks for meetings, standups, and fixed schedules
• 📧 Email Notifications — SMTP integration; assignment, status/priority change, @mention, and due-date reminders
• 🔑 Password Recovery — Forgot-password flow with temporary email reset links
• 🚦 RAG Health Score — Automatic Red/Amber/Green project health indicator
• 📈 Dashboard KPIs & Statistics — Configurable widgets and aggregate reporting
• 📊 Reporting Hub — Organization/portfolio/delivery/capacity packs, expense analytics (optional module), CSV extract, and advanced Explore pivots (/reporting)
• 💸 Expenses (optional) — Project/internal costs, invoice attachments, approval and reimbursement workflow with category caps
• 🔍 Global Search — Cross-entity search with paginated results (including users → profile pages)
• 🔔 Real-Time Updates — Socket.io notifications and live UI refresh
• 🌙 Dark Mode — Full dark mode support across the UI
• 📱 Responsive Design — Mobile-friendly interface with grouped navigation
• 🖥️ Desktop App — Optional Electron wrapper (pnpm run desktop:dev)
• 🧩 IDE Extensions — VS Code / Cursor Kanban sidebar for tasks linked to this app (extras/ide-extensions/README.md⁠)
• 🧙 Install Wizard — Guided first-time setup
• ⚡ Optional Redis Cache — Read-through cache with invalidate-on-write for faster loads; disabled by default
• 🧠 Synapse⁠ — Companion Markdown vaults (SSO with Myelin; optional checkbox→task push)
• 🤖 AI Assistant (optional) — SQL-backed assistant; DB views are created on server start via ensureAiAssistantViews (see server/utils/aiAssistantViews.ts)

⁠Additional Notes

• This README is intentionally concise to comply with Docker Hub overview size limits.
• For feature walkthroughs and conventions, see AGENTS.md⁠, docs/FEATURES.md⁠, and the in-app user manual at /docs.
• Legacy /reports redirects to Reporting → Extract; manager analytics live under /reporting.
• API documentation (Swagger): http://localhost:3000/api-docs when the server is running.

⁠Tech Stack

⁠Local Development

git clone https://github.com/tiag0ss/myelin.git
cd myelin
pnpm install
cp .env.example .env
# Edit .env (database, JWT_SECRET, etc.)

Run the app (Express custom server embeds Next.js on the same port):

pnpm run dev

Open http://localhost:3000, complete the install wizard on first run, then sign in.

Production after pnpm run build:

pnpm start
# same as: pnpm run start:prod

Optional desktop shell:

pnpm run desktop:dev

Run tests:

pnpm test

⁠Quick Start (Docker)

⁠1. Create environment file

cp .env.docker.example .env.docker
# Edit .env.docker with your values

MySQL example (default):

DB_PROVIDER=mysql
DB_HOST=mysql
DB_PORT=3306
DB_USER=appuser
DB_PASSWORD=your-strong-password-here
DB_NAME=projectmanagement
DB_CONNECTION_LIMIT=50

JWT_SECRET=your-super-secret-jwt-key-minimum-64-characters
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
NEXT_PUBLIC_API_URL=http://localhost:3000
API_URL=http://localhost:3000
LOG_LEVEL=warn

MSSQL example:

DB_PROVIDER=mssql
DB_HOST=your-sqlserver-host
DB_PORT=1433
DB_USER=sa
DB_PASSWORD=your-strong-password-here
DB_NAME=projectmanagement
DB_CONNECTION_LIMIT=50
DB_ENCRYPT=false
DB_TRUST_SERVER_CERT=true

JWT_SECRET=your-super-secret-jwt-key-minimum-64-characters
ALLOWED_ORIGINS=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:3000
API_URL=http://localhost:3000
LOG_LEVEL=warn

Optional Redis (faster reads; MySQL/MSSQL remain source of truth):

REDIS_ENABLED=true
REDIS_URL=redis://redis:6379
REDIS_KEY_PREFIX=pm:
REDIS_DEFAULT_TTL_SECONDS=300

Set ENCRYPTION_KEY (64-char hex) in production if you use Jira, Outlook, or other encrypted integration settings. If omitted, JWT_SECRET is used as fallback.

⁠2. Run with Docker Compose

Use the docker-compose.yml⁠ in this repository:

docker compose up -d

With optional Redis cache:

docker compose --profile redis up -d

When using the Redis profile, set REDIS_ENABLED=true and REDIS_URL=redis://redis:6379 in .env.docker.

For MSSQL, point DB_HOST to your SQL Server instance instead of the bundled MySQL service.

⁠3. Run standalone (with external DB)

docker run -d \
  --name myelin \
  -p 3000:3000 \
  --env-file .env.docker \
  tiag0ss/myelin:latest

⁠4. First-Time Setup

1. Open http://localhost:3000 in your browser
2. The Install Wizard guides you through:
   • Admin account creation
   • Organization setup
   • Email configuration (optional)
3. Configure integrations under Administration → System Settings (SMTP, Jira, Outlook, etc.)

⁠Environment Variables

⁠Ports

⁠Volumes

Note: Rich text editor images are stored as base64 in the database, not in the uploads folder.

⁠Health Check

GET http://localhost:3000/health

Example response:

{
  "status": "healthy",
  "timestamp": "2026-07-02T22:00:00.000Z",
  "uptime": 3600,
  "database": "connected",
  "redis": "disabled"
}

redis is connected, disabled, or error. Redis failures do not fail the health check — the app falls back to the database.

If you see stale lists after a create/update with Redis enabled, confirm invalidation is wired on that write route; as a fallback, restart the API or flush Redis keys matching your REDIS_KEY_PREFIX (default pm:*).

⁠Architecture

Single container serves Next.js frontend and Express API. MySQL or MSSQL is the system of record. Redis is optional.

+----------------------------------+
|   myelin:latest      |
|                                  |
|  +-----------+  +------------+   |
|  | Next.js   |  | Express    |   |
|  | Frontend  |  | API        |   |
|  +-----------+  +------------+   |
|         Port 3000                |
+----------------------------------+
          |              |
          |              +-----> Redis (optional)
          |
   +------+------+
   | MySQL / MSSQL |
   +---------------+

• Base image: node:20-alpine
• Runs as: Non-root user (nodejs, UID 1001)
• Process: node dist/server/index.js
• Cache: When REDIS_ENABLED=true, reads are cached with invalidate-on-write; writes always go to the database first

⁠Updating

docker compose pull
docker compose up -d

⁠Backup

⁠Database (MySQL)

docker exec myelin-mysql \
  mysqldump -u root -p"$DB_PASSWORD" projectmanagement > backup.sql

⁠Restore (MySQL)

docker exec -i myelin-mysql \
  mysql -u root -p"$DB_PASSWORD" projectmanagement < backup.sql

For MSSQL, use your standard backup/restore tools (BACKUP DATABASE / RESTORE DATABASE).

⁠Testing

Comprehensive testing scenarios are in TESTING_SCENARIOS.md⁠:

• 220+ test scenarios covering major features
• Authentication, authorization, and security cases
• Integration and end-to-end flows
• Performance and browser compatibility notes

pnpm test
pnpm run test:coverage
pnpm run test:integration

⁠License

MIT

⁠Links

• 🐳 Docker Hub⁠
• 🐛 Report Issues⁠
• 📖 Source Code⁠
• 📬 Cloudflare Email Task Queue⁠
• 🧪 Testing Scenarios⁠