How abubakar471/openmuffin-base works
1. System shape
OpenMuffin is split into two deployable applications: a Next.js frontend in client/ and an Express/TypeScript backend in server/. The product goal is decentralized media sharing, but the repo clearly uses a hybrid architecture: peer-to-peer media transport plus a centralized backend for coordination, validation, and monitoring.
2. Frontend boundary
The client/ app is the user-facing shell built with Next.js + TypeScript. Its app/ directory contains the root layout, global styles, and landing page, while the actual product functionality appears to live in reusable dashboard components under client/components/dashboard/.
3. P2P/media runtime on the client
The client’s P2P logic is centered around client/hooks/useWebRTCStream.ts, which suggests a React hook that manages WebRTC connection lifecycle and stream state. The presence of client/public/workers/stream.worker.ts indicates that some stream handling or chunk processing is offloaded to a web worker to keep heavy media work off the main UI thread.
4. Client-side UI responsibilities
The dashboard component TransferingEngineDashboard.ts likely acts as the main operational surface for transfer status, peer connection state, and streaming metrics. In architecture terms, the client is responsible for:
- user interaction and session state
- WebRTC initiation/control
- visualizing transfer progress and diagnostics
- delegating expensive processing to the worker
5. Backend boundary
The server/ app is a structured Express API with clear layers: routes, controllers, validators, middleware, services, models, and error types. This is the central coordination plane for the system, not the media plane itself.
6. Transfer domain on the server
The main backend domain appears to be transfers. server/src/routes/transfer.route.ts, controllers/transfer.controller.ts, validators/transfer.validator.ts, and models/transfer.model.ts together imply a RESTful transfer-management API that likely creates, updates, and reports transfer sessions or media distribution events.
7. Cross-cutting backend concerns
The backend has dedicated middleware for authentication, validation, and error handling:
- auth.middleware.ts protects selected endpoints or resolves caller identity
- validate.middleware.ts enforces request shape before controller execution
- error.middleware.ts centralizes failure responses
This is a strong signal that request processing is intentionally layered and defensive.
8. Persistence and domain models
The presence of user.model.ts and user.interface.ts shows that the backend tracks at least user identity/account data alongside transfer data. The repository README mentions Dockerized MongoDB and Redis, so the backend likely persists primary state in MongoDB and uses Redis for ephemeral coordination, caching, or real-time transfer state.
9. Monitoring/telemetry path
server/src/services/monitoring.service.ts indicates a dedicated backend service for collecting or aggregating operational metrics. This aligns with the planned “real-time transfer metrics dashboard” in the README, so the architecture likely includes a feedback loop from transfer activity into observable metrics that the frontend can display.
10. Data flow between client and server
The likely system flow is:
- the client opens a transfer/stream session in the dashboard
- the frontend establishes or prepares a WebRTC connection
- the backend validates/authenticates the request and coordinates transfer metadata
- peers exchange media directly over WebRTC data channels/media channels
- the backend receives transfer state/monitoring updates for visibility and control
11. Infrastructure/runtime
The repo is container-oriented: docker-compose.yaml is used to bring up supporting services, and the README explicitly calls for MongoDB + Redis in Docker before running the apps. That means the deployment boundary is not just client/server; it also includes external datastore/cache infrastructure.
12. Repo organization signals
docs/server.md suggests there is backend-specific documentation, while separate package.json files in client/ and server/ confirm independent build/run lifecycles. For an architecture diagram, the clearest top-level boxes are: Browser UI, WebRTC peer connections, Express backend API, MongoDB, Redis, and Dockerized local infrastructure.
Main entry points: app.ts API app · TransferingEngineDashboard.ts Dashboard · useWebRTCStream.ts WebRTC hook · transfer.route.ts Transfer route
Components 20
Client
Next.js browser app and media runtime
- Next app · App shell, layout, and landing page
client/app - Dashboard · Main transfer and session screen
client/components/dashboard/TransferingEngineDashboard.ts - WebRTC hook · Manages peer connection and stream state
client/hooks/useWebRTCStream.ts - Stream worker · Offloads heavy stream or chunk processing
client/public/workers/stream.worker.ts
Server
Express API and backend domain layers
- API app · Wires backend middleware, routes, and services
server/src/app.ts - Server entry · Bootstraps the HTTP server runtime
server/src/server.ts - Transfer route · Transfer-related API endpoints
server/src/routes/transfer.route.ts - Transfer controller · Handles transfer API requests
server/src/controllers/transfer.controller.ts - Transfer validator · Validates transfer payloads
server/src/validators/transfer.validator.ts - Auth middleware · Resolves or protects caller identity
server/src/middlewares/auth.middleware.ts - Validate middleware · Checks request shape before handlers
server/src/middlewares/validate.middleware.ts - Error middleware · Centralized failure handling
server/src/middlewares/error.middleware.ts - Monitoring · Aggregates operational metrics
server/src/services/monitoring.service.ts - Transfer model · Persistent transfer session state
server/src/models/transfer.model.ts - User model · User identity and account data
server/src/models/user.model.ts - User interface · Shared user shape definition
server/src/interfaces/user.interface.ts - App error · Backend domain error wrapper
server/src/errors/app-error.ts
Infrastructure
Local supporting services and deployment glue
- MongoDB · Primary persistent store
docker-compose.yaml - Redis · Ephemeral coordination and state
docker-compose.yaml - Compose stack · Local containerized runtime
docker-compose.yaml
Connections 23
- Next app → Dashboard: renders · The app shell hosts the transfer dashboard
- Dashboard → WebRTC hook: uses · Dashboard drives WebRTC connection state
- WebRTC hook → Stream worker: delegates · Heavy stream processing moves off the main thread
- Dashboard → API app: API calls · UI submits transfer and monitoring requests
- WebRTC hook → API app: signaling · Backend coordinates peer setup and transfer metadata
- Server entry → API app: starts · Server entry boots the Express app
- API app → Auth middleware: applies · Authentication runs before protected handlers
- API app → Validate middleware: applies · Validation runs as request gatekeeper
- API app → Error middleware: applies · Central error handling wraps the app
- API app → Transfer route: mounts · Transfer routes are registered on the API app
- Transfer route → Transfer controller: dispatches · Routes forward work to the controller
- Transfer route → Transfer validator: checks · Route input is validated before handling
- Transfer controller → Transfer model: persists · Controller reads and writes transfer state
- Transfer controller → Monitoring: reports · Transfer activity feeds metrics collection
- Monitoring → Redis: uses · Operational state and fast coordination data
- Transfer model → MongoDB: stores in · Primary transfer records live in MongoDB
- User model → MongoDB: stores in · User data persists in MongoDB
- User model → User interface: implements · Model conforms to shared user contract
- Auth middleware → User model: resolves · Auth middleware relies on user identity data
- Validate middleware → App error: raises · Validation failures become app errors
- Error middleware → App error: formats · Domain errors are normalized for responses
- Compose stack → MongoDB: runs · Compose provisions the database service
- Compose stack → Redis: runs · Compose provisions the cache service