# kkmmtt0919/growth-loop-agent architecture

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

- Interactive diagram: https://gitdiagram.com/kkmmtt0919/growth-loop-agent
- Repository: https://github.com/kkmmtt0919/growth-loop-agent

## Overview

Growth Loop is a personal-improvement agent that turns user logs and goals into planned actions, scheduled execution, and reflection. Its primary loop runs from goal creation and AI action decomposition through availability-aware preview, schedule acceptance, execution check-ins, and evening/weekly review; reflections inform later planning. The graph preserves documented quiz, trace, records, and dashboard capabilities. Most API/service wiring is documented or indexed rather than excerpted, so uncertain implementation links are omitted; README statements support the broader workflow.

Main entry points: [`app/api`](https://github.com/kkmmtt0919/growth-loop-agent/tree/main/app/api) (API routes), [`lib/service`](https://github.com/kkmmtt0919/growth-loop-agent/tree/main/lib/service) (Service layer), [`lib/repo`](https://github.com/kkmmtt0919/growth-loop-agent/tree/main/lib/repo) (Repository layer), [`app/page.tsx`](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/page.tsx) (Web experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web experience<br/>[page.tsx]"]
  node_chat["Chat panel<br/>[chat-panel.tsx]"]
  node_records_ui["Records view<br/>[page.tsx]"]
  node_weekly_ui["Growth view<br/>[page.tsx]"]
end

subgraph group_planning["Goals and planning"]
  node_goals["Goal management<br/>[goals.ts]"]
  node_decompose["Action decomposition"]
  node_planner["Smart Planner<br/>[planner.ts]"]
  node_availability["Availability<br/>[availability.ts]"]
  node_timeline["Schedule timeline<br/>[timeline.ts]"]
  node_execution["Execution check-in<br/>[execution.ts]"]
end

subgraph group_learning["Agent and review"]
  node_chat_agent["Conversation agent<br/>[chat.ts]"]
  node_agent_core["Agent rules<br/>[pure.ts]"]
  node_records["Learning records<br/>[records.ts]"]
  node_quiz["Understanding quiz<br/>[quiz.ts]"]
  node_evening["Evening review<br/>[evening.ts]"]
  node_weekly["Weekly report<br/>[weekly.ts]"]
  node_reflection["Reflection feedback<br/>[reflection.ts]"]
  node_trace["Agent run trace<br/>[agent-runs.ts]"]
end

subgraph group_platform["Application platform"]
  node_api["API routes"]
  node_auth["JWT authentication<br/>[middleware.ts]"]
  node_services["Service layer"]
  node_repositories["Repository layer"]
  node_postgres[("PostgreSQL")]
end

node_user(("User"))
node_llm{{"Compatible LLM"}}
node_cron(("Cron caller"))

node_user -->|"uses"| node_web
node_web -->|"opens"| node_chat
node_web -.->|"requests"| node_api
node_chat -.->|"sends chat"| node_api
node_records_ui -.->|"loads records"| node_api
node_weekly_ui -.->|"loads growth"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"dispatches"| node_services
node_services -->|"queries"| node_repositories
node_repositories -->|"reads/writes"| node_postgres
node_api -->|"routes goals"| node_goals
node_api -->|"routes actions"| node_decompose
node_goals -->|"requests breakdown"| node_decompose
node_api -->|"routes availability"| node_availability
node_api -.->|"routes planning"| node_planner
node_api -->|"routes schedules"| node_timeline
node_api -.->|"routes check-ins"| node_execution
node_api -->|"routes chat"| node_chat_agent
node_chat_agent -.->|"uses rules"| node_agent_core
node_api -.->|"routes records"| node_records
node_api -->|"routes quiz"| node_quiz
node_api -->|"routes reviews"| node_evening
node_cron -->|"triggers report"| node_api
node_api -.->|"routes weekly"| node_weekly
node_api -->|"routes feedback"| node_reflection
node_reflection -->|"informs planning"| node_planner
node_api -.->|"routes traces"| node_trace
node_chat_agent -.->|"calls optionally"| node_llm
node_planner -.->|"generates optionally"| node_llm
node_evening -.->|"generates optionally"| node_llm
node_quiz -.->|"grades optionally"| node_llm
node_api -->|"agent writes records"| node_records
node_api -->|"stores sessions"| node_quiz
node_api -->|"tasks route"| node_services
node_services -->|"task queries"| node_repositories
node_repositories -->|"task SQL"| node_postgres

click node_web "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/page.tsx"
click node_chat "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/chat-panel.tsx"
click node_records_ui "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/records/page.tsx"
click node_weekly_ui "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/weekly/page.tsx"
click node_goals "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/goals.ts"
click node_decompose "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/action-decompose.ts"
click node_planner "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/planner.ts"
click node_availability "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/availability.ts"
click node_timeline "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/timeline.ts"
click node_execution "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/execution.ts"
click node_chat_agent "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/chat.ts"
click node_agent_core "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/agent/core/pure.ts"
click node_records "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/records.ts"
click node_quiz "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/agent/quiz.ts"
click node_evening "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/evening.ts"
click node_weekly "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/weekly.ts"
click node_reflection "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/reflection.ts"
click node_trace "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/agent-runs.ts"
click node_api "https://github.com/kkmmtt0919/growth-loop-agent/tree/main/app/api"
click node_auth "https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/auth/middleware.ts"
click node_services "https://github.com/kkmmtt0919/growth-loop-agent/tree/main/lib/service"
click node_repositories "https://github.com/kkmmtt0919/growth-loop-agent/tree/main/lib/repo"

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_web,node_chat,node_records_ui,node_weekly_ui,node_user toneBlue
class node_goals,node_decompose,node_planner,node_availability,node_timeline,node_execution toneAmber
class node_chat_agent,node_agent_core,node_records,node_quiz,node_evening,node_weekly,node_reflection,node_trace toneMint
class node_api,node_auth,node_services,node_repositories,node_postgres toneRose
class node_llm,node_cron toneIndigo
```

## Components

### User experience

- [Web experience](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/page.tsx): `app/page.tsx`
- [Chat panel](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/chat-panel.tsx): `app/chat-panel.tsx`
- [Records view](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/records/page.tsx): `app/records/page.tsx`
- [Growth view](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/app/weekly/page.tsx): `app/weekly/page.tsx`

### Goals and planning

- [Goal management](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/goals.ts): `lib/service/goals.ts`
- [Action decomposition](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/action-decompose.ts): `lib/service/action-decompose.ts`
- [Smart Planner](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/planner.ts): `lib/service/planner.ts`
- [Availability](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/availability.ts): `lib/service/availability.ts`
- [Schedule timeline](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/timeline.ts): `lib/service/timeline.ts`
- [Execution check-in](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/execution.ts): `lib/service/execution.ts`

### Agent and review

- [Conversation agent](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/chat.ts): `lib/service/chat.ts`
- [Agent rules](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/agent/core/pure.ts): `lib/agent/core/pure.ts`
- [Learning records](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/records.ts): `lib/service/records.ts`
- [Understanding quiz](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/agent/quiz.ts): `lib/agent/quiz.ts`
- [Evening review](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/evening.ts): `lib/service/evening.ts`
- [Weekly report](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/weekly.ts): `lib/service/weekly.ts`
- [Reflection feedback](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/reflection.ts): `lib/service/reflection.ts`
- [Agent run trace](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/service/agent-runs.ts): `lib/service/agent-runs.ts`

### Application platform

- [API routes](https://github.com/kkmmtt0919/growth-loop-agent/tree/main/app/api): `app/api`
- [JWT authentication](https://github.com/kkmmtt0919/growth-loop-agent/blob/main/lib/auth/middleware.ts): `lib/auth/middleware.ts`
- [Service layer](https://github.com/kkmmtt0919/growth-loop-agent/tree/main/lib/service): `lib/service`
- [Repository layer](https://github.com/kkmmtt0919/growth-loop-agent/tree/main/lib/repo): `lib/repo`
- **PostgreSQL**

### Other components

- **User**
- **Compatible LLM**
- **Cron caller**

## Connections

- User → Web experience: uses (evidence: `README.md`)
- Web experience → Chat panel: opens (evidence: `app/page.tsx`)
- Web experience → API routes: requests
- Chat panel → API routes: sends chat
- Records view → API routes: loads records
- Growth view → API routes: loads growth
- API routes → JWT authentication: authenticates (evidence: `README.md`)
- API routes → Service layer: dispatches (evidence: `README.md`)
- Service layer → Repository layer: queries (evidence: `README.md`)
- Repository layer → PostgreSQL: reads/writes (evidence: `README.md`)
- API routes → Goal management: routes goals (evidence: `app/api/goals/route.ts`)
- API routes → Action decomposition: routes actions (evidence: `app/api/actions/route.ts`)
- Goal management → Action decomposition: requests breakdown (evidence: `lib/service/goals.ts`)
- API routes → Availability: routes availability (evidence: `app/api/availability/route.ts`)
- API routes → Smart Planner: routes planning
- API routes → Schedule timeline: routes schedules (evidence: `app/api/schedules/route.ts`)
- API routes → Execution check-in: routes check-ins
- API routes → Conversation agent: routes chat (evidence: `app/api/chat/route.ts`)
- Conversation agent → Agent rules: uses rules
- API routes → Learning records: routes records
- API routes → Understanding quiz: routes quiz (evidence: `app/api/quiz/route.ts`)
- API routes → Evening review: routes reviews (evidence: `app/api/evening-report/route.ts`)
- Cron caller → API routes: triggers report (evidence: `README.md`)
- API routes → Weekly report: routes weekly
- API routes → Reflection feedback: routes feedback (evidence: `app/api/reflections/route.ts`)
- Reflection feedback → Smart Planner: informs planning (evidence: `README.md`)
- API routes → Agent run trace: routes traces
- Conversation agent → Compatible LLM: calls optionally
- Smart Planner → Compatible LLM: generates optionally (evidence: `README.md`)
- Evening review → Compatible LLM: generates optionally (evidence: `README.md`)
- Understanding quiz → Compatible LLM: grades optionally (evidence: `README.md`)
- API routes → Learning records: agent writes records (evidence: `app/api/agent/route.ts`)
- API routes → Understanding quiz: stores sessions (evidence: `app/api/quiz/route.ts`)
- API routes → Service layer: tasks route (evidence: `app/api/tasks/route.ts`)
- Service layer → Repository layer: task queries (evidence: `lib/service/tasks.ts`)
- Repository layer → PostgreSQL: task SQL (evidence: `lib/repo/tasks.ts`)