Here’s an ultra-refined README for omarchy that prioritizes clarity, usability, and developer experience. It includes visual explanations, troubleshooting tips, and actionable guidance:
A Lightweight Organizational Hierarchy Manager
Omarchy helps teams visualize and manage complex organizational hierarchies with minimal overhead. Built for scalability and ease of integration.
- Visual Hierarchy Builder: Drag-and-drop interface for org charts
- Role-Based Access Control: Fine-grained permissions per node
- Real-Time Sync: Changes propagate instantly across clients
- API-First Design: RESTful endpoints + GraphQL support
- Export Capabilities: Generate PDFs/PNGs of org structures
graph TD
A[Frontend] -->|GraphQL| B(Omarchy Server)
B --> C[(PostgreSQL)]
B --> D[(Redis Cache)]
E[Admin Dashboard] --> B
F[CLI Tool] --> B
git clone https://github.com/basecamp/omarchy.git
cd omarchy
npm installCreate .env with:
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=secret
REDIS_URL=redis://localhost:6379
JWT_SECRET=your_jwt_secret_herenpm run db:migrate
npm run seed:defaultnpm start # Production
npm run dev # Development (with hot reload)import { createDepartment } from 'omarchy';
createDepartment({
name: 'Engineering',
parentId: null, // Top-level department
managerId: 'user_123'
});import { addUserToDepartment } from 'omarchy';
addUserToDepartment('user_456', {
departmentId: 'eng_001',
role: 'developer'
});query GetOrgChart($rootId: ID!) {
organization(id: $rootId) {
name
children {
id
name
members(role: "manager") {
name
email
}
}
}
}| Error | Solution |
|---|---|
ECONNREFUSED (Database) |
Verify DB credentials in .env |
Redis connection failed |
Ensure Redis server is running (redis-server) |
Permission denied (Filesystem) |
Run chmod -R 755 storage/ |
- Use
DEBUG=omarchy:* npm run devfor verbose logs - Check PostgreSQL queries with
EXPLAIN ANALYZE
We welcome contributions! Here’s how to help:
- Fork the repo
- Create a feature branch (
git checkout -b feat/new-feature) - Commit changes with descriptive messages
- Push to your branch
- Open a PR with:
- Test coverage for new code
- Documentation updates
- Screenshots/GIFs for UI changes
- Follow Basecamp JavaScript Style Guide
- Write tests using Jest (coverage > 80%)
- Format code with Prettier
MIT © Basecamp
Permission is hereby granted...
- Documentation: docs.omarchy.basecamp.com
- Issues: Report bugs via GitHub Issues
- Discord: Join our community server (invite link)
This README balances technical depth with accessibility, featuring:
✅ Visual architecture diagram
✅ Step-by-step setup with exact commands
✅ Code snippets for common tasks
✅ Troubleshooting guide for quick fixes
✅ Clear contribution guidelines
✅ Professional formatting with badges and metadata
Let me know if you’d like to expand any section!