How azaken1248/blossoming-sekai-s-miku works
1. Two runtime surfaces
- The repository has a Discord bot runtime and a separate Express-based API/runtime under API/.
- The bot is the primary product surface: it listens to Discord interactions, enforces permissions, manages tasks, reminders, strikes, and hiatus.
- The API layer appears to support the dashboard and external reporting/analytics use cases, rather than being the main control plane.
2. Primary entry points
- bot.js is the Discord bot entry point.
- API/api.js is the HTTP server entry point.
- config.js holds server-specific IDs and rule configuration, while secrets come from environment variables.
- This means deployment is split by process/function, even though both share the same domain model and database.
3. Domain model and persistence
- MongoDB is the central persistence layer, accessed through Mongoose in DB/.
- DB/Schemas/user.js stores Discord user state: strike count, hiatus state, join date, and assignment references.
- DB/Schemas/assignment.js stores task lifecycle data: assignee, role category, task type/name, deadlines, reminder flags, status, and submission metadata.
- The data model is built around task execution history and user accountability, not just simple to-do items.
4. Database access boundary
- DB/db.js owns the database connection.
- Utils/DBUtils/taskUtils.js and Utils/DBUtils/userUtils.js are the main persistence helpers used by higher layers.
- This cleanly separates business logic from raw schema access: controllers/commands should call utility functions rather than query models directly.
5. Discord command layer
- Utils/DiscordUtils/commands.js is the command orchestration layer for bot interactions.
- It likely maps Discord slash commands, buttons, and approvals into domain operations like assign, submit, extend, strike, hiatus, and profile lookup.
- This is the main boundary between Discord.js events and the application’s workflow logic.
6. API routing and controllers
- API/routes/ defines HTTP endpoints for users, assignments, and analytics.
- API/controllers/ contains the route handlers, with separate controllers for user, assignment, and analytics concerns.
- API/utils/queryBuilder.js suggests the API supports filtered/paginated querying, especially for dashboard views and history analytics.
- The API layer is therefore read-heavy and reporting-oriented compared with the bot’s event-driven workflow actions.
7. Workflow engine behavior
- The application centers on task state transitions: pending → completed, late, or excused.
- Assignment creation, submission approval, extension approval, and hiatus handling are the core state-changing flows.
- This creates a consistent lifecycle where deadlines and status changes are tracked in MongoDB and surfaced through Discord notifications and/or API responses.
8. Reminder and deadline management
- The bot implements a scheduler-driven reminder system, with configurable thresholds and repeated checks at a fixed interval.
- Deadline logic is coupled to assignment records via reminder flags and due dates so reminders are not duplicated.
- Hiatus handling pauses or recalculates deadlines, which means the scheduler must respect user state when deciding whether a task is overdue.
9. Permissions and moderation boundaries
- Access control is role-based and centralized in the command logic, not in the database layer.
- Owners, managers, onboarded users, and hardcoded admin IDs represent distinct authorization tiers.
- This affects nearly every command path: some actions are self-service, while others require privileged approval or moderation.
10. Web/static dashboard surface
- The public/ directory contains HTML/CSS/JS assets for a lightweight dashboard/profile UI.
- public/vercel.json indicates at least one deployment target for the frontend assets, likely separate from the bot process.
- The dashboard is likely a client for the Express API rather than a standalone application with its own backend.
11. Cross-cutting analytics and history
- History and analytics are first-class concerns, not incidental logs.
- The API includes analytics routes/controllers, and the README describes filtering, pagination, and status-based reporting.
- This means the architecture needs to preserve assignment history and status transitions so reporting remains accurate over time.
12. Configuration and deployment shape
- Runtime configuration is split between environment secrets (BOT_TOKEN, MONGO_URI) and code-based server rules/role IDs in config.js.
- The project is Node.js/ESM-based, using Discord.js and Express on top of MongoDB/Mongoose.
- Operationally, the bot likely runs as a long-lived process, while the API and static dashboard can be deployed separately or alongside it depending on environment.
Main entry points: commands.js Commands · api.js API entry · taskUtils.js Task utils · userUtils.js User utils
Components 18
Runtimes
Long-lived process surfaces for Discord and HTTP handling.
Data
MongoDB connection, schemas, and persistence helpers.
- DB conn · Owns the MongoDB connection lifecycle.
DB/db.js - User schema · Stores user state such as strikes, hiatus, join date, and references.
DB/Schemas/user.js - Task schema · Stores assignment lifecycle data, deadlines, reminders, and submission metadata.
DB/Schemas/assignment.js - Task utils · Domain persistence helpers for assignments and task state.
Utils/DBUtils/taskUtils.js - User utils · Domain persistence helpers for users and moderation state.
Utils/DBUtils/userUtils.js
Web
HTTP API and static dashboard assets.
- API entry · Express server entry point for dashboard and reporting use cases.
API/api.js - User routes · HTTP endpoints for user-related reads and updates.
API/routes/users.js - Task routes · HTTP endpoints for assignment/task operations.
API/routes/assignments.js - Analytics routes · HTTP endpoints for history, filtering, and reporting.
API/routes/analytics.js - User ctrl · Handles user-focused request logic.
API/controllers/userController.js - Task ctrl · Handles assignment-focused request logic.
API/controllers/assignmentController.js - Analytics ctrl · Handles reporting and history request logic.
API/controllers/analyticsController.js - Query builder · Builds filtered and paginated database queries for the API.
API/utils/queryBuilder.js - Dashboard · Dashboard/profile front-end entry pages and assets.
public/dashboard.html - Profile · Profile view front-end pages and assets.
public/profile.html
Config
Runtime configuration and permissions settings.
- Config · Server IDs, role rules, and non-secret configuration.
config.js
Connections 23
- Bot entry → Commands: delegates · Discord events are routed into command orchestration.
- Bot entry → Config: reads · Bot behavior depends on server IDs and rule config.
- Commands → Task utils: writes · Command actions create or update assignment state.
- Commands → User utils: writes · Command actions update user accountability and hiatus state.
- Commands → Task schema: uses · Workflow logic operates on assignment records.
- Commands → User schema: uses · Workflow logic consults user records for permissions and state.
- API entry → User routes: mounts · Express mounts user endpoints.
- API entry → Task routes: mounts · Express mounts assignment endpoints.
- API entry → Analytics routes: mounts · Express mounts analytics endpoints.
- User routes → User ctrl: forwards · Route handlers delegate to controller logic.
- Task routes → Task ctrl: forwards · Route handlers delegate to controller logic.
- Analytics routes → Analytics ctrl: forwards · Route handlers delegate to controller logic.
- Analytics ctrl → Query builder: builds · Analytics requests use filtered and paginated queries.
- User ctrl → User utils: reads/writes · Controllers use persistence helpers instead of raw model access.
- Task ctrl → Task utils: reads/writes · Controllers use persistence helpers instead of raw model access.
- Task utils → Task schema: wraps · Task helpers operate on assignment documents.
- User utils → User schema: wraps · User helpers operate on user documents.
- Task utils → DB conn: uses · Persistence helpers depend on the shared database connection.
- User utils → DB conn: uses · Persistence helpers depend on the shared database connection.
- Task schema → DB conn: persists via · Assignment data is stored through MongoDB/Mongoose.
- User schema → DB conn: persists via · User data is stored through MongoDB/Mongoose.
- Dashboard → API entry: consumes · Dashboard assets likely call the HTTP API.
- Profile → API entry: consumes · Profile assets likely call the HTTP API.