Modern Enterprise Resource Planning (ERP) system built with Domain-Driven Design
Replace multiple SaaS tools with one modular platform: CRM, Orders, Inventory, Billing, Accounting, and Fiscal compliance — designed for Ukrainian and European SMB market.
Manage your entire sales pipeline from lead to customer, track interactions, and grow your business.
- Customer Management — Companies, contacts, segmentation, lifecycle tracking
- Deal Pipeline — Sales opportunities, stages, probability scoring, forecasting
- Interaction History — Calls, meetings, emails, notes with full audit trail
- Sales Analytics — Revenue reports, conversion metrics, team performance
🎯 For: Sales teams, account managers, customer success
📚 Documentation: Customer Management Context
Process orders efficiently with automated workflows, real-time tracking, and fulfillment orchestration.
- Order Processing — Multi-channel orders, complex pricing, promotions
- Fulfillment Workflows — Automated state machines: pending → confirmed → processing → fulfilled
- Saga Orchestration — Coordinate inventory, billing, and fiscal operations
- Order Analytics — Sales metrics, fulfillment KPIs, bottleneck detection
🎯 For: E-commerce, B2B distributors, service businesses
📚 Documentation: Order Management Context
Track inventory across multiple locations with real-time visibility and automated stock management.
- Multi-Warehouse — Unlimited locations with hierarchical organization
- Product Catalog — SKU management, categories, variants, pricing
- Stock Movements — Receipts, reservations, transfers, adjustments with full audit
- Low Stock Alerts — Automated reorder points, stock forecasting
🎯 For: Retailers, distributors, manufacturers
📚 Documentation: Warehouse Context
Generate invoices, track payments, and manage recurring billing with automatic subscription handling.
- Invoice Generation — Automatic from orders, manual creation, templates
- Payment Tracking — Multiple payment methods, partial payments, refunds
- Recurring Billing — Subscriptions, trials, plan upgrades, automatic renewals
- Payment Analytics — Cash flow, aging reports, revenue recognition
🎯 For: SaaS companies, subscription businesses, B2B services
📚 Documentation: Billing Context
Complete financial management with chart of accounts, journal entries, and financial reporting.
- Chart of Accounts — Flexible account hierarchy, multi-currency support
- Journal Entries — Double-entry bookkeeping, automatic posting, audit trail
- Cost Centers & Budgets — Department tracking, budget planning, variance analysis
- Financial Reports — Balance sheet, P&L, cash flow, custom reports
🎯 For: Finance teams, accountants, CFOs
📚 Documentation: Accounting Context
Connect to bank accounts, import transactions, and automate reconciliation.
- Bank Accounts — Multiple accounts per organization, multi-currency
- Transaction Import — Bank statement parsing, automatic categorization
- Reconciliation — Match transactions with invoices and payments
- Cash Management — Cash position, forecast, treasury operations
🎯 For: Finance teams, treasury management
📚 Documentation: Banking Context
Built-in integration with Ukrainian tax authorities and ПРРО (fiscal cash registers).
- Checkbox Integration — Automatic receipt generation, fiscal reporting
- ПРРО Support — Cash register operations, Z-reports, fiscal documents
- Tax Compliance — VAT tracking, tax reports, electronic submission
- Audit Trail — Complete transaction history for tax audits
🎯 For: Ukrainian businesses, tax compliance officers
📚 Documentation: Fiscal Context
Enterprise-grade user management with role-based access control.
- User Management — Users, contacts, profiles, multi-organization support
- Authentication — JWT-based, secure password hashing (Argon2id), MFA-ready
- Authorization — Role-based access control (RBAC), permissions, API keys
- Audit Logging — User actions, security events, compliance tracking
🎯 For: IT administrators, security teams
📚 Documentation: Identity Context
Replace expensive ERP systems (SAP, 1C, Bitrix24) with flexible, cost-effective solution:
- E-commerce stores — Integrate with online shops, manage inventory, automate fulfillment
- B2B distributors — Handle complex pricing, track customer relationships, manage warehouses
- Service businesses — Manage projects, track time, invoice clients, recurring billing
Business Value: Market Analysis & ROI
Build custom business solutions on proven foundation:
- SaaS platforms — Use as backend for vertical SaaS products
- Custom ERP — Extend with industry-specific modules
- Integration projects — Connect existing systems via event-driven architecture
Technical Details: Architecture Overview
Purpose-built for Ukrainian business requirements:
- Fiscal compliance — ПРРО, Checkbox, tax reporting
- Local banking — Monobank, PrivatBank integration (roadmap)
- Language support — Ukrainian, Russian, English interfaces
- Market opportunity: $45M+ TAM, 180K+ potential customers
Market Strategy: Ukraine Market Analysis
Get Promenade running in 5 minutes:
- Go 1.24+ — Install Go
- Docker — Install Docker
- Make — Usually pre-installed on macOS/Linux
# 1. Clone repository
git clone https://github.com/basilex/promenade.git
cd promenade
# 2. Start PostgreSQL and run migrations
make docker-up
make migrate
# 3. Start API server
make dev🎉 That's it! Server is running at http://localhost:8081
# Health check
curl http://localhost:8081/health
# API documentation (Swagger UI)
open http://localhost:8081/api/docs/index.html- Complete Setup Guide — User registration, authentication, first API calls
- API Documentation — Swagger UI guide, Postman collection
- Development Workflow — Daily commands, testing, debugging
- Postman Examples — Ready-to-use API call examples
Promenade is built on strict DDD principles with 8 bounded contexts that communicate only via events:
┌─────────────────────────────────────────────────────────────┐
│ Event Bus │
│ (Async communication layer) │
└─────────────────────────────────────────────────────────────┘
│ │ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│Identity │Customer │ Order │ Billing │Warehouse│ Fiscal │Accounting│
│ │ Mgmt │ Mgmt │ │ │ │ & Bank │
└─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘
Own DB Own DB Own DB Own DB Own DB Own DB Own DB
-
Bounded Context Autonomy
- Each context owns its domain model, database schema, and business logic
- No shared database tables between contexts
- Independent deployment and scaling
-
No Cross-Context Imports
- Contexts communicate only through Event Bus
- No direct Go imports between contexts
- Uses Anti-Corruption Layer (ACL) for integration
-
Clean Architecture Layers
- Domain Layer — Aggregates, entities, value objects, business rules
- Application Layer — Use cases, orchestration, transaction boundaries
- Infrastructure Layer — Database, HTTP, event handlers
- Presentation Layer — DTOs, HTTP handlers, API routes
-
Event-Driven Integration
- Domain events published after state changes
- Asynchronous processing with guaranteed delivery
- Saga pattern for distributed transactions
📚 Learn More:
- Bounded Contexts Deep Dive
- Clean Architecture Explained
- Event-Driven Patterns
- Fulfillment Saga Pattern
Backend Core:
- Language: Go 1.24 — Performance, concurrency, type safety
- Database: PostgreSQL 16+ — ACID compliance, JSON support
- HTTP: Gin framework — High performance, middleware ecosystem
- Auth: JWT (RS256) — Stateless, secure, scalable
Infrastructure:
- Event Bus: In-memory (dev), Redis (production) — 377K events/sec
- Cache: Redis — Session storage, rate limiting
- Migrations: Custom manager — Multi-namespace, rollback support
- Monitoring: Health checks, metrics, structured logging
Development:
- Testing: 4-tier strategy — Unit, smoke, integration, benchmarks
- API Docs: Swagger/OpenAPI 3.0 — Interactive documentation
- Git Hooks: Pre-commit linting, pre-push testing
- CI/CD: GitHub Actions — Automated testing, deployment
📚 Learn More:
promenade/
├── cmd/ # Application entry points
│ ├── api/ # HTTP API server
│ │ ├── main.go # Entry point
│ │ ├── bootstrap.go # Infrastructure setup
│ │ ├── dependencies.go # Custom DI container
│ │ └── server.go # HTTP routing
│ ├── migrate/ # Migration runner
│ └── seed/ # Test data seeder
│
├── internal/ # Private application code
│ ├── contexts/ # Bounded contexts (DDD)
│ │ ├── identity/ # Users, auth, permissions
│ │ ├── customer-mgmt/ # CRM, deals, interactions
│ │ ├── order-mgmt/ # Orders, fulfillment
│ │ ├── billing/ # Invoices, payments
│ │ ├── warehouse/ # Inventory, products
│ │ ├── fiscal/ # Cash registers, receipts
│ │ ├── accounting/ # Chart of accounts, journals
│ │ └── banking/ # Bank accounts, reconciliation
│ └── infrastructure/ # Cross-cutting concerns
│ ├── database/ # Connection, transactions
│ ├── auth/ # JWT, password hashing
│ └── http/ # Middleware, responses
│
├── pkg/ # Reusable packages
│ ├── bus/ # Event Bus (377K events/sec)
│ ├── aggregate/ # Base aggregate, change tracking
│ ├── jsonstore/ # Type-safe JSON fields
│ ├── uuidv7/ # Time-ordered UUIDs
│ └── middleware/ # Auth, CORS, rate limiting
│
├── migrations/ # Database migrations
│ └── postgres/ # PostgreSQL migrations
│ ├── core/ # System tables
│ ├── identity/ # Identity context
│ ├── customer-mgmt/ # Customer management
│ └── .../ # Other contexts
│
├── test/ # Test suites
│ ├── integration/ # Full workflow tests
│ ├── smoke/ # Fast CRUD checks
│ └── benchmark/ # Performance tests
│
├── docs/ # Documentation
│ ├── business/ # Business overviews (8 languages)
│ ├── concepts/ # Architecture concepts
│ ├── guides/ # Development guides
│ ├── deployment/ # Kubernetes, AWS, Docker
│ └── adr/ # Architecture Decision Records
│
└── config/ # Configuration files
├── app.postgres-dev.yaml # PostgreSQL development
├── app.postgres-prod.yaml # PostgreSQL production
└── .../ # Other configs
Each Bounded Context follows clean architecture:
internal/contexts/{context}/
├── {aggregate}/ # Domain subdomain
│ ├── aggregate/ # Domain entities & business logic
│ ├── repository/ # Repository interface
│ ├── usecase/ # Application use cases
│ ├── adapter/
│ │ ├── repository/
│ │ │ └── postgres/ # PostgreSQL implementation
│ │ └── http/ # HTTP handlers
│ ├── dto/ # Data Transfer Objects
│ └── errors.go # Domain error constants
└── README.md # Context documentation
📚 Learn More: Context Structure Guide
Promenade uses 4-tier testing approach for comprehensive quality assurance:
| Level | Count | Speed | Database | Purpose |
|---|---|---|---|---|
| Unit | 200+ | < 1s | ❌ Mock | Business logic, pure functions |
| Smoke | 26 | < 5s | ✅ Real | Basic CRUD, fast feedback loop |
| Integration | 29 | ~30s | ✅ Real | Full workflows, cross-aggregate |
| Benchmark | 15+ | < 10s | ⚡ Memory | Performance, regression detection |
# All tests (recommended before commit)
make test
# Individual test levels
make test-unit # Unit tests only (fast)
make test-smoke # Smoke tests (basic CRUD)
make test-integration # Integration tests (full workflows)
make test-benchmark # Performance benchmarks
# Pre-push validation (lint + all tests + build)
make pre-push
# Specific package
go test ./internal/contexts/customer-mgmt/...
go test ./pkg/bus/... -bench=.✅ All tests passing
- Unit: 200+ tests, 100% passing
- Smoke: 26/26 contexts, < 5s runtime
- Integration: 29/29 tests, full database workflows
- Benchmarks: Event Bus 377K events/sec, UUID 100M/sec
- Unit tests — Next to source files (
*_test.go) - Smoke tests — Mirror structure in
test/smoke/contexts/ - Integration tests — Group by context in
test/integration/contexts/ - Coverage target — 80%+ for critical business logic
📚 Learn More: Complete Testing Guide
For Decision Makers & Stakeholders
- Business Overview — Platform capabilities, market opportunity, ROI
- Available in: 🇬🇧 English, 🇺🇦 Ukrainian, 🇪🇸 Spanish, 🇩🇪 German, 🇫🇷 French, 🇵🇹 Portuguese, 🇨🇳 Chinese, 🇯🇵 Japanese
- Ukraine Market Strategy — Market analysis, TAM $45M+, GTM strategy
- Implementation Status — Feature completion, development roadmap
- Deployment Options — Kubernetes, AWS, Docker Compose, monitoring
Getting Started
- Quick Start Guide — 5-minute setup, first API calls
- API Documentation — Swagger UI, Postman collection
- Development Workflow — Daily commands, debugging, troubleshooting
- Contributing Guide — Code standards, PR process, git hooks
Architecture & Patterns
- Clean Architecture — Layers, dependencies, testability
- Bounded Contexts — DDD principles, context isolation
- Event-Driven Architecture — Event Bus, domain events, sagas
- Fulfillment Saga — Distributed transaction orchestration
Development Guides
- Security Patterns — Authentication, authorization, error handling
- Database Strategy — PostgreSQL patterns, migrations, transactions
- Error Handling — Domain errors, HTTP responses, logging
- JSON Fields — Type-safe JSONB handling
- Profiling — CPU/memory profiling, pprof, optimization
Architecture Decision Records
- ADR-0001: Use UUID v7 — Time-ordered UUIDs for better DB performance
- ADR-0002: Use sqlx over GORM — Control, performance, maintainability
- ADR-0003: Use Redis for Caching — Distributed cache strategy
- ADR Template — Template for new ADRs
Each context has detailed README with domain model, use cases, and API examples:
- Identity — Users, authentication, RBAC
- Customer Management — CRM, deals, interactions
- Order Management — Orders, fulfillment workflows
- Billing — Invoices, payments, subscriptions
- Warehouse — Inventory, products, stock movements
- Accounting — Chart of accounts, journal entries
- Banking — Bank accounts, reconciliation
- Fiscal — ПРРО, Checkbox integration
Reusable packages with usage examples and benchmarks:
- Event Bus — In-memory & Redis, 377K events/sec
- Aggregates — Base aggregate, change tracking, Touch()
- JSON Store — Type-safe JSONB fields
- UUIDv7 — Time-ordered IDs, 100M/sec generation
- Value Objects — Email, phone, money, address
- Postman Collection — Import-ready API collection
- Customer Management Examples — CRM workflows
- Order Management Examples — Order processing
- Billing Examples — Invoice & payment flows
We welcome contributions! Promenade follows strict code standards to maintain quality.
- Read CONTRIBUTING.md — Code standards, PR process
- Set up git hooks:
make setup-hooks— Automatic linting and testing - Review Architecture Decision Records — Understand design choices
# 1. Create feature branch
git checkout -b feature/your-feature-name
# 2. Make changes and test
make test # Run all tests
make lint # Check code style
# 3. Pre-push validation (automatic via git hook)
make pre-push # Lint + tests + build
# 4. Commit and push
git add .
git commit -m "feat: add amazing feature"
git push origin feature/your-feature-name- Go — Follow Effective Go and project conventions
- DDD — Respect bounded context boundaries, no cross-context imports
- Testing — Add tests for new features (smoke + integration)
- Documentation — Update README and context docs for public APIs
- Commits — Follow Conventional Commits
High-Priority Areas:
- 🔌 Integrations — Payment gateways, shipping providers, accounting systems
- 🌍 Localization — UI translations, fiscal compliance for other countries
- 📊 Analytics — Reports, dashboards, data visualization
- 🔒 Security — Audit, penetration testing, security hardening
- 📱 Clients — SDKs for popular languages (Python, PHP, JavaScript)
Good First Issues: Check GitHub Issues
- ✅ 8 bounded contexts with clean architecture
- ✅ Customer Management (CRM)
- ✅ Order Management with fulfillment workflows
- ✅ Warehouse & Inventory
- ✅ Billing & Invoicing
- ✅ Accounting (Chart of Accounts, Journal Entries)
- ✅ Banking Integration
- ✅ Fiscal Compliance (ПРРО, Checkbox)
- ✅ Event-driven architecture (377K events/sec)
- ✅ Comprehensive test coverage (200+ tests)
- ✅ API documentation (Swagger/OpenAPI)
- 🔄 Multi-tenancy — Organization isolation, data partitioning
- 🔄 Frontend — Next.js admin panel, Flutter mobile app
- 🔄 Advanced Analytics — BI dashboards, custom reports
- 🔄 Monobank Integration — Bank statement import, automatic reconciliation
- 🔄 Email/SMS — Transactional notifications, marketing campaigns
- 📅 CRM Enhancements — Marketing automation, lead scoring, pipeline analytics
- 📅 Advanced Billing — Usage-based pricing, revenue recognition, dunning
- 📅 Procurement — Purchase orders, supplier management, receiving
- 📅 Manufacturing — Bill of materials, production orders, shop floor tracking
- 📅 Project Management — Projects, tasks, time tracking, resource planning
- 📅 HR Module — Employees, payroll, attendance, leave management
- 📅 Mobile Apps — iOS/Android native apps with offline support
- 📅 AI/ML — Demand forecasting, churn prediction, smart recommendations
📚 Full Roadmap: Project Roadmap
MIT License — See LICENSE file for details.
The core Promenade backend API (v0.1.0-dev) is free and open source:
- ✅ Backend API with 11 bounded contexts
- ✅ PostgreSQL database layer (pgx driver)
- ✅ Event-driven architecture
- ✅ Complete documentation and tests
- ✅ Free for commercial and non-commercial use
- ✅ Self-hosted deployment
Advanced features are available under commercial licenses in separate private repositories:
🎨 Promenade UI (promenade-ui - private repository)
- Next.js Admin Panel with modern UI/UX
- Flutter Mobile App (iOS/Android)
- Design system and component library
- White-label customization
- License: Proprietary, paid subscription required
🏢 Promenade Enterprise (promenade-enterprise - private repository)
- Multi-tenancy and organization isolation
- Advanced analytics and BI dashboards
- Bank integrations (Monobank, PrivatBank, etc.)
- Advanced billing and subscription management
- Email/SMS notifications
- Priority support and SLA
- License: Proprietary, enterprise agreement required
Community (Free)
- Core backend API (this repo)
- Self-hosted
- Community support
Professional ($99/month)
- Core backend API
- UI/UX (web + mobile)
- Up to 3 organizations
- Email support
Enterprise (Custom)
- Everything in Professional
- Unlimited organizations
- Advanced analytics
- Bank integrations
- Priority support
- Custom development
Contact: alexander.vasilenko@gmail.com for commercial inquiries
Note: This open-core model ensures the core backend remains free and open source, while protecting commercial investments in UI/UX and enterprise features. Commercial modules are kept in private repositories to prevent unauthorized use.
Built with love using:
- Go — Google's systems programming language
- PostgreSQL — World's most advanced open source database
- Gin — High-performance HTTP framework
- Redis — In-memory data structure store
- Swagger — API documentation and testing
Special thanks to the DDD community and all contributors!
- 📧 Email: support@promenade.dev
- 💬 Discord: Join our community
- 🐛 Issues: GitHub Issues
- 📖 Docs: Documentation Site
- 🐦 Twitter: @PromenadeERP
⭐ Star us on GitHub — it helps!
Documentation • API Reference • Contributing
Made with ❤️ for Ukrainian businesses