# azaken1248/blossoming-sekai-s-miku architecture

> Architecture diagram of the GitHub repository azaken1248/blossoming-sekai-s-miku, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azaken1248/blossoming-sekai-s-miku
- Repository: https://github.com/azaken1248/blossoming-sekai-s-miku

## Overview

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: [`Utils/DiscordUtils/commands.js`](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DiscordUtils/commands.js) (Commands), [`API/api.js`](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/api.js) (API entry), [`Utils/DBUtils/taskUtils.js`](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DBUtils/taskUtils.js) (Task utils), [`Utils/DBUtils/userUtils.js`](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DBUtils/userUtils.js) (User utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtimes"]
  node_bot["Bot entry<br/>discord runtime<br/>[bot.js]"]
  node_discord_cmds["Commands<br/>discord orchestration<br/>[commands.js]"]
end

subgraph group_data["Data"]
  node_db_conn[("DB conn<br/>mongoose connection<br/>[db.js]")]
  node_user_schema["User schema<br/>mongoose model<br/>[user.js]"]
  node_assignment_schema["Task schema<br/>mongoose model<br/>[assignment.js]"]
  node_task_utils["Task utils<br/>db helper<br/>[taskUtils.js]"]
  node_user_utils["User utils<br/>db helper<br/>[userUtils.js]"]
end

subgraph group_web["Web"]
  node_api_server["API entry<br/>http runtime<br/>[api.js]"]
  node_user_routes["User routes<br/>api routes<br/>[users.js]"]
  node_assignment_routes["Task routes<br/>api routes<br/>[assignments.js]"]
  node_analytics_routes["Analytics routes<br/>api routes<br/>[analytics.js]"]
  node_user_controller["User ctrl<br/>api controller<br/>[userController.js]"]
  node_assignment_controller["Task ctrl<br/>api controller"]
  node_analytics_controller["Analytics ctrl<br/>api controller"]
  node_query_builder["Query builder<br/>api helper<br/>[queryBuilder.js]"]
  node_dashboard_html["Dashboard<br/>static ui<br/>[dashboard.html]"]
  node_profile_html["Profile<br/>static ui<br/>[profile.html]"]
end

subgraph group_config["Config"]
  node_config["Config<br/>[config.js]"]
end

node_bot -->|"delegates"| node_discord_cmds
node_bot -->|"reads"| node_config
node_discord_cmds -->|"writes"| node_task_utils
node_discord_cmds -->|"writes"| node_user_utils
node_discord_cmds -.->|"uses"| node_assignment_schema
node_discord_cmds -.->|"uses"| node_user_schema
node_api_server -->|"mounts"| node_user_routes
node_api_server -->|"mounts"| node_assignment_routes
node_api_server -->|"mounts"| node_analytics_routes
node_user_routes -->|"forwards"| node_user_controller
node_assignment_routes -->|"forwards"| node_assignment_controller
node_analytics_routes -->|"forwards"| node_analytics_controller
node_analytics_controller -->|"builds"| node_query_builder
node_user_controller -->|"reads/writes"| node_user_utils
node_assignment_controller -->|"reads/writes"| node_task_utils
node_task_utils -->|"wraps"| node_assignment_schema
node_user_utils -->|"wraps"| node_user_schema
node_task_utils -->|"uses"| node_db_conn
node_user_utils -->|"uses"| node_db_conn
node_assignment_schema -.->|"persists via"| node_db_conn
node_user_schema -.->|"persists via"| node_db_conn
node_dashboard_html -.->|"consumes"| node_api_server
node_profile_html -.->|"consumes"| node_api_server

click node_bot "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/bot.js"
click node_discord_cmds "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DiscordUtils/commands.js"
click node_api_server "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/api.js"
click node_user_routes "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/routes/users.js"
click node_assignment_routes "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/routes/assignments.js"
click node_analytics_routes "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/routes/analytics.js"
click node_user_controller "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/controllers/userController.js"
click node_assignment_controller "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/controllers/assignmentController.js"
click node_analytics_controller "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/controllers/analyticsController.js"
click node_query_builder "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/utils/queryBuilder.js"
click node_db_conn "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/DB/db.js"
click node_user_schema "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/DB/Schemas/user.js"
click node_assignment_schema "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/DB/Schemas/assignment.js"
click node_task_utils "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DBUtils/taskUtils.js"
click node_user_utils "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DBUtils/userUtils.js"
click node_config "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/config.js"
click node_dashboard_html "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/public/dashboard.html"
click node_profile_html "https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/public/profile.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bot,node_discord_cmds toneBlue
class node_db_conn,node_user_schema,node_assignment_schema,node_task_utils,node_user_utils toneAmber
class node_api_server,node_user_routes,node_assignment_routes,node_analytics_routes,node_user_controller,node_assignment_controller,node_analytics_controller,node_query_builder,node_dashboard_html,node_profile_html toneMint
class node_config toneRose
```

## Components

### Runtimes

Long-lived process surfaces for Discord and HTTP handling.

- [Bot entry](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/bot.js): discord runtime · Discord bot process entry point. · `bot.js`
- [Commands](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DiscordUtils/commands.js): discord orchestration · Maps Discord interactions into domain actions and approvals. · `Utils/DiscordUtils/commands.js`

### Data

MongoDB connection, schemas, and persistence helpers.

- [DB conn](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/DB/db.js): mongoose connection · Owns the MongoDB connection lifecycle. · `DB/db.js`
- [User schema](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/DB/Schemas/user.js): mongoose model · Stores user state such as strikes, hiatus, join date, and references. · `DB/Schemas/user.js`
- [Task schema](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/DB/Schemas/assignment.js): mongoose model · Stores assignment lifecycle data, deadlines, reminders, and submission metadata. · `DB/Schemas/assignment.js`
- [Task utils](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DBUtils/taskUtils.js): db helper · Domain persistence helpers for assignments and task state. · `Utils/DBUtils/taskUtils.js`
- [User utils](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/Utils/DBUtils/userUtils.js): db helper · Domain persistence helpers for users and moderation state. · `Utils/DBUtils/userUtils.js`

### Web

HTTP API and static dashboard assets.

- [API entry](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/api.js): http runtime · Express server entry point for dashboard and reporting use cases. · `API/api.js`
- [User routes](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/routes/users.js): api routes · HTTP endpoints for user-related reads and updates. · `API/routes/users.js`
- [Task routes](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/routes/assignments.js): api routes · HTTP endpoints for assignment/task operations. · `API/routes/assignments.js`
- [Analytics routes](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/routes/analytics.js): api routes · HTTP endpoints for history, filtering, and reporting. · `API/routes/analytics.js`
- [User ctrl](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/controllers/userController.js): api controller · Handles user-focused request logic. · `API/controllers/userController.js`
- [Task ctrl](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/controllers/assignmentController.js): api controller · Handles assignment-focused request logic. · `API/controllers/assignmentController.js`
- [Analytics ctrl](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/controllers/analyticsController.js): api controller · Handles reporting and history request logic. · `API/controllers/analyticsController.js`
- [Query builder](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/API/utils/queryBuilder.js): api helper · Builds filtered and paginated database queries for the API. · `API/utils/queryBuilder.js`
- [Dashboard](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/public/dashboard.html): static ui · Dashboard/profile front-end entry pages and assets. · `public/dashboard.html`
- [Profile](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/public/profile.html): static ui · Profile view front-end pages and assets. · `public/profile.html`

### Config

Runtime configuration and permissions settings.

- [Config](https://github.com/azaken1248/blossoming-sekai-s-miku/blob/main/config.js): runtime config · Server IDs, role rules, and non-secret configuration. · `config.js`

## Connections

- 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.
