# recycle385/calendar architecture

> Architecture diagram of the GitHub repository recycle385/calendar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/recycle385/calendar
- Repository: https://github.com/recycle385/calendar

## Overview

moim is a shared-link scheduling and date-voting service. Hosts create calendars and set candidate dates and a voting window; members or guests join, vote, and see results update in real time, after which the host or an automatic job can close the calendar. The graph combines that user workflow with documented analysis, guest-record reconciliation, holiday synchronization, and optional email. Several backend subsystems are represented by their existing directories because their implementation files were not sampled; those connections are documented capabilities, not claims about inspected call sites.

Main entry points: [`back-end/src/controllers`](https://github.com/recycle385/calendar/tree/main/back-end/src/controllers) (Request controllers), [`back-end/src/config/database.ts`](https://github.com/recycle385/calendar/blob/main/back-end/src/config/database.ts) (MySQL data), [`back-end/src/services/cron.service.ts`](https://github.com/recycle385/calendar/blob/main/back-end/src/services/cron.service.ts) (Scheduled jobs), [`back-end/src/services/auth.service.ts`](https://github.com/recycle385/calendar/blob/main/back-end/src/services/auth.service.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_frontend["SPA screens"]
  node_calendar_ui["Calendar workflows"]
  node_vote_ui["Vote experience"]
  node_http["HTTP client<br/>[httpClient.ts]"]
  node_socket_client["Socket client<br/>[socketClient.ts]"]
  node_cache["Calendar cache<br/>[calendarCache.ts]"]
end

subgraph group_api["HTTP application"]
  node_routes["API routes"]
  node_controllers["Request controllers"]
end

subgraph group_domain["Scheduling domain"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_calendar["Calendar management"]
  node_participants["Participant management"]
  node_voting["Voting<br/>[vote.service.ts]"]
  node_analysis["Vote analysis"]
end

subgraph group_realtime["Realtime and jobs"]
  node_realtime_server["Socket.IO server"]
  node_scheduled_jobs["Scheduled jobs<br/>[cron.service.ts]"]
end

subgraph group_data["Data and integrations"]
  node_mysql[("MySQL data<br/>[database.ts]")]
  node_redis[("Redis state<br/>[redis.ts]")]
  node_google["Google OAuth"]
  node_groq["Groq API"]
  node_holiday_api["Public data API"]
  node_gmail["Gmail API"]
end

node_host(("Host or participant"))

node_host -->|"uses"| node_frontend
node_frontend -->|"presents"| node_calendar_ui
node_calendar_ui -->|"requests"| node_http
node_vote_ui -->|"requests"| node_http
node_http -->|"calls API"| node_routes
node_routes -->|"dispatches"| node_controllers
node_controllers -->|"delegates"| node_auth
node_controllers -->|"delegates"| node_calendar
node_controllers -->|"delegates"| node_participants
node_controllers -.->|"delegates"| node_voting
node_controllers -.->|"delegates"| node_analysis
node_auth -->|"authenticates"| node_google
node_auth -->|"persists users"| node_mysql
node_auth -.->|"uses tokens"| node_redis
node_calendar -->|"reads and writes"| node_mysql
node_participants -->|"reads and writes"| node_mysql
node_voting -.->|"stores votes"| node_mysql
node_host -->|"creates calendar"| node_calendar_ui
node_calendar_ui -.->|"joins participants"| node_participants
node_vote_ui -.->|"submits votes"| node_voting
node_realtime_server -->|"broadcasts changes"| node_socket_client
node_socket_client -->|"signals refresh"| node_cache
node_controllers -->|"emits updates"| node_realtime_server
node_controllers -->|"disconnects users"| node_realtime_server
node_analysis -.->|"analyzes votes"| node_groq
node_scheduled_jobs -.->|"closes calendars"| node_calendar
node_scheduled_jobs -.->|"emails results"| node_gmail
node_scheduled_jobs -.->|"cleans expired data"| node_mysql
node_scheduled_jobs -.->|"syncs holidays"| node_holiday_api

click node_frontend "https://github.com/recycle385/calendar/tree/main/frontend/src/app/pages"
click node_calendar_ui "https://github.com/recycle385/calendar/tree/main/frontend/src/app/pages/calendar"
click node_vote_ui "https://github.com/recycle385/calendar/tree/main/frontend/src/domains/vote"
click node_http "https://github.com/recycle385/calendar/blob/main/frontend/src/shared/api/httpClient.ts"
click node_socket_client "https://github.com/recycle385/calendar/blob/main/frontend/src/shared/socket/socketClient.ts"
click node_cache "https://github.com/recycle385/calendar/blob/main/frontend/src/app/cache/calendarCache.ts"
click node_routes "https://github.com/recycle385/calendar/tree/main/back-end/src/routes"
click node_controllers "https://github.com/recycle385/calendar/tree/main/back-end/src/controllers"
click node_auth "https://github.com/recycle385/calendar/blob/main/back-end/src/services/auth.service.ts"
click node_calendar "https://github.com/recycle385/calendar/blob/main/back-end/src/services/calendar.service.ts"
click node_participants "https://github.com/recycle385/calendar/blob/main/back-end/src/services/participant.service.ts"
click node_voting "https://github.com/recycle385/calendar/blob/main/back-end/src/services/vote.service.ts"
click node_analysis "https://github.com/recycle385/calendar/blob/main/back-end/src/services/analysis.service.ts"
click node_realtime_server "https://github.com/recycle385/calendar/tree/main/back-end/src/sockets"
click node_scheduled_jobs "https://github.com/recycle385/calendar/blob/main/back-end/src/services/cron.service.ts"
click node_mysql "https://github.com/recycle385/calendar/blob/main/back-end/src/config/database.ts"
click node_redis "https://github.com/recycle385/calendar/blob/main/back-end/src/config/redis.ts"

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_frontend,node_calendar_ui,node_vote_ui,node_http,node_socket_client,node_cache toneBlue
class node_routes,node_controllers toneAmber
class node_auth,node_calendar,node_participants,node_voting,node_analysis toneMint
class node_realtime_server,node_scheduled_jobs toneRose
class node_mysql,node_redis,node_google,node_groq,node_holiday_api,node_gmail,node_host toneIndigo
```

## Components

### Web application

- [SPA screens](https://github.com/recycle385/calendar/tree/main/frontend/src/app/pages): `frontend/src/app/pages`
- [Calendar workflows](https://github.com/recycle385/calendar/tree/main/frontend/src/app/pages/calendar): `frontend/src/app/pages/calendar`
- [Vote experience](https://github.com/recycle385/calendar/tree/main/frontend/src/domains/vote): `frontend/src/domains/vote`
- [HTTP client](https://github.com/recycle385/calendar/blob/main/frontend/src/shared/api/httpClient.ts): `frontend/src/shared/api/httpClient.ts`
- [Socket client](https://github.com/recycle385/calendar/blob/main/frontend/src/shared/socket/socketClient.ts): `frontend/src/shared/socket/socketClient.ts`
- [Calendar cache](https://github.com/recycle385/calendar/blob/main/frontend/src/app/cache/calendarCache.ts): `frontend/src/app/cache/calendarCache.ts`

### HTTP application

- [API routes](https://github.com/recycle385/calendar/tree/main/back-end/src/routes): `back-end/src/routes`
- [Request controllers](https://github.com/recycle385/calendar/tree/main/back-end/src/controllers): `back-end/src/controllers`

### Scheduling domain

- [Authentication](https://github.com/recycle385/calendar/blob/main/back-end/src/services/auth.service.ts): `back-end/src/services/auth.service.ts`
- [Calendar management](https://github.com/recycle385/calendar/blob/main/back-end/src/services/calendar.service.ts): `back-end/src/services/calendar.service.ts`
- [Participant management](https://github.com/recycle385/calendar/blob/main/back-end/src/services/participant.service.ts): `back-end/src/services/participant.service.ts`
- [Voting](https://github.com/recycle385/calendar/blob/main/back-end/src/services/vote.service.ts): `back-end/src/services/vote.service.ts`
- [Vote analysis](https://github.com/recycle385/calendar/blob/main/back-end/src/services/analysis.service.ts): `back-end/src/services/analysis.service.ts`

### Realtime and jobs

- [Socket.IO server](https://github.com/recycle385/calendar/tree/main/back-end/src/sockets): `back-end/src/sockets`
- [Scheduled jobs](https://github.com/recycle385/calendar/blob/main/back-end/src/services/cron.service.ts): `back-end/src/services/cron.service.ts`

### Data and integrations

- [MySQL data](https://github.com/recycle385/calendar/blob/main/back-end/src/config/database.ts): `back-end/src/config/database.ts`
- [Redis state](https://github.com/recycle385/calendar/blob/main/back-end/src/config/redis.ts): `back-end/src/config/redis.ts`
- **Google OAuth**
- **Groq API**
- **Public data API**
- **Gmail API**

### Other components

- **Host or participant**

## Connections

- Host or participant → SPA screens: uses
- SPA screens → Calendar workflows: presents
- Calendar workflows → HTTP client: requests
- Vote experience → HTTP client: requests
- HTTP client → API routes: calls API
- API routes → Request controllers: dispatches (evidence: `back-end/src/routes/calendar.routes.ts`)
- Request controllers → Authentication: delegates (evidence: `back-end/src/controllers/auth.controller.ts`)
- Request controllers → Calendar management: delegates (evidence: `back-end/src/controllers/calendar.controller.ts`)
- Request controllers → Participant management: delegates (evidence: `back-end/src/controllers/participant.controller.ts`)
- Request controllers → Voting: delegates
- Request controllers → Vote analysis: delegates
- Authentication → Google OAuth: authenticates (evidence: `back-end/src/services/auth.service.ts`)
- Authentication → MySQL data: persists users (evidence: `back-end/src/services/auth.service.ts`)
- Authentication → Redis state: uses tokens
- Calendar management → MySQL data: reads and writes (evidence: `back-end/src/services/calendar.service.ts`)
- Participant management → MySQL data: reads and writes (evidence: `back-end/src/services/participant.service.ts`)
- Voting → MySQL data: stores votes
- Host or participant → Calendar workflows: creates calendar
- Calendar workflows → Participant management: joins participants
- Vote experience → Voting: submits votes
- Socket.IO server → Socket client: broadcasts changes
- Socket client → Calendar cache: signals refresh
- Request controllers → Socket.IO server: emits updates (evidence: `back-end/src/controllers/calendar.controller.ts`)
- Request controllers → Socket.IO server: disconnects users (evidence: `back-end/src/controllers/participant.controller.ts`)
- Vote analysis → Groq API: analyzes votes
- Scheduled jobs → Calendar management: closes calendars
- Scheduled jobs → Gmail API: emails results
- Scheduled jobs → MySQL data: cleans expired data
- Scheduled jobs → Public data API: syncs holidays