How composecraft/composecraft works
Project Type and Purpose
• Compose Craft is a full-stack web application built with Next.js (app router), TypeScript and React-Flow. It provides a GUI to create, edit, share and export Docker Compose files.
• It combines a React-based client UI, a Node.js/Next.js server API, a MongoDB database, and several external integrations (OAuth, email, telemetry).
Key Architectural Layers and Components
A. Client (Browser)
• Next.js pages/components under app/ and components/
• React-Flow based playground for visual editing (components/playground)
• UI elements (buttons, tables, forms) under components/ui
• Global CSS, Tailwind, fonts, static assets in app/globals.css and public/
B. Server API (Next.js Node Runtime)
• API routes under app/api/ (auth, compose, ping)
• Edge middleware (middleware.ts)
• Business logic and service calls implemented in actions/ (e.g., composeActions.ts, userActions.ts)
• Data access and utilities under lib/ (MongoDB connector, models, JWT auth, Brevo email, Directus)
C. Persistence
• MongoDB (collections: users, compositions, telemetry data)
• Models defined in lib/models/*.ts
D. External Services
• GitHub OAuth (login)
• Directus (optional CMS integration)
• Brevo (email notifications)
• Umami (self-hosted telemetry)
E. DevOps & Deployment
• Dockerfile + docker-compose.yml for container orchestration
• CI/CD workflows in .github/workflows/ and .gitlab-ci.yml
• Environment variables for secrets, MongoDB URI, feature toggles
Relationships and Data Flow
1. User loads UI → Next.js SSR/SSR-stream renders pages + React hydrates.
2. In the playground: client interacts with React-Flow, updates local Zustand store (store/).
3. On save/share → client issues fetch to POST /api/compose → Next.js route handler invokes composeActions, validates/serializes YAML, stores record in MongoDB via lib/mongodb.
4. Share endpoint generates a public URL, stores metadata, possibly triggers Brevo email.
5. Auth flow: client ↔ /api/auth/external (GitHub OAuth) or /api/auth/jwt for token issuance → JWT stored in cookie/localStorage.
6. Telemetry events sent client-side to Umami (external).
Architectural Patterns & Principles
• Layered architecture: UI → API → Business Logic → Data Layer
• Single monorepo full-stack approach using Next.js “app” directory for server and client code.
• Separation of concerns:
• components/ for UI
• actions/ for use-case orchestration
• lib/ for data access and integration utilities
• store/ for client state (Zustand)
• Environment-driven feature flags (CORE_ONLY, DISABLE_TELEMETRY)