# jirasak-thongpila/nudge architecture

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

- Interactive diagram: https://gitdiagram.com/jirasak-thongpila/nudge
- Repository: https://github.com/jirasak-thongpila/nudge

## Overview

Nudge turns task input into dynamically prioritized work, detects possible avoidance, and helps users begin via a short focus session or an Action Nudge. The backend also supports Gemini text/audio parsing, LINE chat and LIFF integration, and an overview dashboard. The Flutter application source is not present in this tree, so clients are represented as external actors rather than inferred frontend modules. The graph follows documented capabilities and sampled route/service calls; unsampled subsystem links are limited to README-documented relationships.

Main entry points: [`backend/src/app.ts`](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/app.ts) (Elysia API), [`backend/src/services/task.service.ts`](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/task.service.ts) (Task Management), [`backend/src/services/line.service.ts`](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/line.service.ts) (LINE Messaging), [`backend/src/plugins/auth.ts`](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/plugins/auth.ts) (Device / LINE Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and Identity"]
  node_api["Elysia API<br/>[app.ts]"]
  node_auth["Device / LINE Auth<br/>[auth.ts]"]
  node_users["User Management<br/>[user.service.ts]"]
  node_taskroutes["Task Routes<br/>[tasks.ts]"]
  node_dashboard["Overview Dashboard<br/>[dashboard.ts]"]
  node_focusroutes["Focus Routes<br/>[focus.ts]"]
  node_nudgeroutes["Nudge Routes<br/>[nudges.ts]"]
  node_lineroutes["LINE Routes<br/>[line.ts]"]
end

subgraph group_work["Task Intelligence"]
  node_taskservice["Task Management<br/>[task.service.ts]"]
  node_priority["Priority Engine<br/>[priority.ts]"]
  node_avoidance["Avoidance Detection<br/>[avoidance.ts]"]
  node_dates["Deadline Calculation<br/>[date.ts]"]
end

subgraph group_engage["Focus and Nudges"]
  node_focus["Focus Sessions<br/>[focus.service.ts]"]
  node_nudges["Nudge Dispatch<br/>[nudge.service.ts]"]
  node_nudgepolicy["Nudge Selection<br/>[nudge.ts]"]
end

subgraph group_integrations["External Integrations"]
  node_parser["Gemini Task Parser<br/>[gemini.service.ts]"]
  node_line["LINE Messaging<br/>[line.service.ts]"]
  node_geminiapi["Google Gemini API"]
  node_lineapi["LINE Messaging API"]
end

subgraph group_persistence["Persistence"]
  node_database[("PostgreSQL / Neon<br/>[schema.ts]")]
end

node_clients(("Flutter App / LIFF"))
node_linechat(("LINE Chat"))
node_scheduler["Nudge Scheduler<br/>[dispatch-nudges.ts]"]

node_clients -->|"REST requests"| node_api
node_linechat -->|"Webhook events"| node_api
node_scheduler -->|"dispatch request"| node_api
node_api -->|"registers routes"| node_taskroutes
node_api -->|"registers routes"| node_dashboard
node_api -->|"registers routes"| node_focusroutes
node_api -->|"registers routes"| node_lineroutes
node_api -->|"registers routes"| node_nudgeroutes
node_taskroutes -->|"authenticates"| node_auth
node_taskroutes -->|"manages tasks"| node_taskservice
node_taskroutes -->|"parses audio"| node_parser
node_dashboard -->|"gets dashboard"| node_taskservice
node_focusroutes -->|"authenticates"| node_auth
node_focusroutes -->|"manages sessions"| node_focus
node_nudgeroutes -->|"authenticates"| node_auth
node_nudgeroutes -->|"dispatches nudges"| node_nudges
node_lineroutes -->|"authenticates"| node_auth
node_lineroutes -->|"handles LINE"| node_line
node_auth -->|"resolves identity"| node_users
node_taskservice -->|"calculates scores"| node_priority
node_taskservice -->|"detects avoidance"| node_avoidance
node_taskservice -->|"calculates deadlines"| node_dates
node_focus -->|"updates task status"| node_taskservice
node_nudges -->|"selects candidate"| node_nudgepolicy
node_nudges -->|"sends action nudge"| node_line
node_line -->|"sends messages"| node_lineapi
node_line -->|"reads tasks"| node_taskservice
node_line -->|"resolves LINE user"| node_users
node_line -->|"interprets messages"| node_parser
node_parser -->|"parses task input"| node_geminiapi
node_taskservice -->|"reads and writes"| node_database
node_users -->|"reads and writes"| node_database
node_focus -->|"records sessions"| node_database

click node_scheduler "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/scripts/dispatch-nudges.ts"
click node_api "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/app.ts"
click node_auth "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/plugins/auth.ts"
click node_users "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/user.service.ts"
click node_taskroutes "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/tasks.ts"
click node_dashboard "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/dashboard.ts"
click node_taskservice "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/task.service.ts"
click node_priority "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/priority.ts"
click node_avoidance "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/avoidance.ts"
click node_dates "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/date.ts"
click node_parser "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/gemini.service.ts"
click node_focusroutes "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/focus.ts"
click node_focus "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/focus.service.ts"
click node_nudgeroutes "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/nudges.ts"
click node_nudges "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/nudge.service.ts"
click node_nudgepolicy "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/nudge.ts"
click node_lineroutes "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/line.ts"
click node_line "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/line.service.ts"
click node_database "https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/db/schema.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_api,node_auth,node_users,node_taskroutes,node_dashboard,node_focusroutes,node_nudgeroutes,node_lineroutes toneBlue
class node_taskservice,node_priority,node_avoidance,node_dates toneAmber
class node_focus,node_nudges,node_nudgepolicy toneMint
class node_parser,node_line,node_geminiapi,node_lineapi,node_scheduler toneRose
class node_database,node_clients,node_linechat toneIndigo
```

## Components

### API and Identity

- [Elysia API](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Device / LINE Auth](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/plugins/auth.ts): `backend/src/plugins/auth.ts`
- [User Management](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/user.service.ts): `backend/src/services/user.service.ts`
- [Task Routes](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/tasks.ts): `backend/src/routes/tasks.ts`
- [Overview Dashboard](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/dashboard.ts): `backend/src/routes/dashboard.ts`
- [Focus Routes](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/focus.ts): `backend/src/routes/focus.ts`
- [Nudge Routes](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/nudges.ts): `backend/src/routes/nudges.ts`
- [LINE Routes](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/routes/line.ts): `backend/src/routes/line.ts`

### Task Intelligence

- [Task Management](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/task.service.ts): `backend/src/services/task.service.ts`
- [Priority Engine](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/priority.ts): `backend/src/lib/priority.ts`
- [Avoidance Detection](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/avoidance.ts): `backend/src/lib/avoidance.ts`
- [Deadline Calculation](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/date.ts): `backend/src/lib/date.ts`

### Focus and Nudges

- [Focus Sessions](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/focus.service.ts): `backend/src/services/focus.service.ts`
- [Nudge Dispatch](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/nudge.service.ts): `backend/src/services/nudge.service.ts`
- [Nudge Selection](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/lib/nudge.ts): `backend/src/lib/nudge.ts`

### External Integrations

- [Gemini Task Parser](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/gemini.service.ts): `backend/src/services/gemini.service.ts`
- [LINE Messaging](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/services/line.service.ts): `backend/src/services/line.service.ts`
- **Google Gemini API**
- **LINE Messaging API**

### Persistence

- [PostgreSQL / Neon](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`

### Other components

- **Flutter App / LIFF**
- **LINE Chat**
- [Nudge Scheduler](https://github.com/jirasak-thongpila/nudge/blob/main/backend/src/scripts/dispatch-nudges.ts): `backend/src/scripts/dispatch-nudges.ts`

## Connections

- Flutter App / LIFF → Elysia API: REST requests
- LINE Chat → Elysia API: Webhook events
- Nudge Scheduler → Elysia API: dispatch request
- Elysia API → Task Routes: registers routes (evidence: `backend/src/app.ts`)
- Elysia API → Overview Dashboard: registers routes (evidence: `backend/src/app.ts`)
- Elysia API → Focus Routes: registers routes (evidence: `backend/src/app.ts`)
- Elysia API → LINE Routes: registers routes (evidence: `backend/src/app.ts`)
- Elysia API → Nudge Routes: registers routes (evidence: `backend/src/app.ts`)
- Task Routes → Device / LINE Auth: authenticates (evidence: `backend/src/routes/tasks.ts`)
- Task Routes → Task Management: manages tasks (evidence: `backend/src/routes/tasks.ts`)
- Task Routes → Gemini Task Parser: parses audio (evidence: `backend/src/routes/tasks.ts`)
- Overview Dashboard → Task Management: gets dashboard (evidence: `backend/src/routes/dashboard.ts`)
- Focus Routes → Device / LINE Auth: authenticates (evidence: `backend/src/routes/focus.ts`)
- Focus Routes → Focus Sessions: manages sessions (evidence: `backend/src/routes/focus.ts`)
- Nudge Routes → Device / LINE Auth: authenticates (evidence: `backend/src/routes/nudges.ts`)
- Nudge Routes → Nudge Dispatch: dispatches nudges (evidence: `backend/src/routes/nudges.ts`)
- LINE Routes → Device / LINE Auth: authenticates (evidence: `backend/src/routes/line.ts`)
- LINE Routes → LINE Messaging: handles LINE (evidence: `backend/src/routes/line.ts`)
- Device / LINE Auth → User Management: resolves identity (evidence: `backend/src/plugins/auth.ts`)
- Task Management → Priority Engine: calculates scores (evidence: `backend/src/services/task.service.ts`)
- Task Management → Avoidance Detection: detects avoidance (evidence: `backend/src/services/task.service.ts`)
- Task Management → Deadline Calculation: calculates deadlines (evidence: `backend/src/services/task.service.ts`)
- Focus Sessions → Task Management: updates task status (evidence: `backend/src/services/focus.service.ts`)
- Nudge Dispatch → Nudge Selection: selects candidate (evidence: `backend/src/services/nudge.service.ts`)
- Nudge Dispatch → LINE Messaging: sends action nudge (evidence: `backend/src/services/nudge.service.ts`)
- LINE Messaging → LINE Messaging API: sends messages (evidence: `backend/src/services/line.service.ts`)
- LINE Messaging → Task Management: reads tasks (evidence: `backend/src/services/line.service.ts`)
- LINE Messaging → User Management: resolves LINE user (evidence: `backend/src/services/line.service.ts`)
- LINE Messaging → Gemini Task Parser: interprets messages (evidence: `backend/src/services/line.service.ts`)
- Gemini Task Parser → Google Gemini API: parses task input
- Task Management → PostgreSQL / Neon: reads and writes (evidence: `backend/src/services/task.service.ts`)
- User Management → PostgreSQL / Neon: reads and writes (evidence: `backend/src/services/user.service.ts`)
- Focus Sessions → PostgreSQL / Neon: records sessions (evidence: `backend/src/services/focus.service.ts`)
