Welcome to the ISLAMU Event documentation hub. To provide the best possible experience for both operators and engineers, our documentation is cleanly separated into two distinct tracks:
docs/
├── README.md <-- You are here (The Documentation Router)
├── public/ <-- Public Documentation (Synced with GitBook for Adopters & Operators)
└── internal/ <-- Engineering Brain (For Contributors, Architects & AI Coding Agents)
| I am a... | Goal | Go To |
|---|---|---|
| Adopter / Self-Hoster / Operator | Deploying, operating, or configuring an instance (Docker, Coolify, Traefik) | 📖 Public Documentation (Also available online at islamu.gitbook.io/islamu-event) |
| Community Admin / Organizer | Managing events, ticketing, white-labeling, or tenant branding via UI | 🏢 Administration Guides |
| API Integrator | Integrating third-party apps or building clients against the REST API | 🔌 API Reference & Cookbook |
| Developer Contributor | Contributing C# backend, Blazor frontend, or architecture improvements | 💻 Internal Developer Docs (Start with internal/DEVELOPER_GUIDE.md) |
| AI Coding Agent | Pair programming, verifying invariants, running tests, or planning tasks | 🤖 AGENTS.md & internal/index.md |
Hosted Portal: https://islamu.gitbook.io/islamu-event
This directory is the source of truth for the public GitBook site. It is curated for clarity, actionable step-by-step guidance, and ease of adoption without exposing internal framework mechanics.
- Getting Started: 5-minute evaluation, architectural concepts, and platform advantages.
- Self-Hosting: Production topologies using Docker Compose, Coolify, Traefik, or standalone containers.
- Configuration & Operations: Environment variable matrices, secrets injection, backup, restore, and health checks.
- Security & Identity: Authentication with Keycloak, tenant isolation, and privacy erasure.
- Events & Ticketing: Modular aspects, custom registration properties, admission credentials, and payouts.
- API Reference: HAL-REST concepts, interactive endpoints, and task-first recipes.
- Changelog: Adopter-facing release notes, upgrade instructions, and breaking change announcements.
This directory is the engineering brain for core maintainers and AI coding agents. It contains exhaustive technical truth, Clean Architecture rules, CQRS patterns, database policies, and repository constraints.
- Documentation Index: Comprehensive inventory of all 90+ internal technical guides.
- Quick Reference: Non-negotiable repository invariants, critical rules, and constraints.
- Architecture & Layer Rules: Domain, Application, Infrastructure, API, and Blazor layer boundaries.
- Domain Model: Aggregate roots, entities, invariants, and state machines.
- API Contract & HAL Rules: RFC 9457 ProblemDetails, HAL link affordances, output caching, and versioning.
- Configuration & Manifests: Complete binding paths, schema types, fallback hierarchy, and manifest specifications.
- Hosting Architecture: Composition roots (Explore.API, Explore.Blazor, Event.Standalone), startup lifecycle phases, and provider abstraction.
- Operations & Verification: Build, test, CI/CD runbooks, Aspire local hosting, and diagnostic tooling.
- Architecture Decision Records (ADRs): Permanent record of architectural choices and tradeoffs.
To prevent public docs and internal technical truth from drifting apart, this repository enforces a Dual-Documentation Parity & Separation Rule:
Rule: Any change impacting external behavior (environment variables, docker-compose services, public API endpoints, authentication flows, or self-hosting runbooks) MUST update both tracks in the same pull request:
- Update the Public Guide in
docs/public/(adopter-friendly operational guide, copy-pasteable configurations, no internal C# classes).- Update the Technical Anchor in
docs/internal/(exhaustive architectural specification, C# code bindings, DDD invariants). Both tracks fulfill distinct responsibilities without duplicating content or cluttering each other's audience.
See docs/internal/DOCUMENTATION_ARCHITECTURE.md for the complete Documentation Twin Parity Matrix and verification instructions.