# joabss/correai-api architecture

> Architecture diagram of the GitHub repository joabss/correai-api, 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/joabss/correai-api
- Repository: https://github.com/joabss/correai-api

## Overview

CorreAI is an anonymous-user running and walking API. A client obtains a JWT, then submits and browses activities and requests goal progress and performance statistics. The graph follows the documented hexagonal boundary from web controllers through application services to persistence and token adapters. Source excerpts show activity, goal, and statistics orchestration; the README documents authentication middleware and the broader port-to-adapter wiring. Persistence and middleware implementation details were not sampled, so their edges rely on that documentation.

Main entry points: [`src/main/java/com/correai/api/application/activity/ActivityApplicationService.java`](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/activity/ActivityApplicationService.java) (Activity workflow), [`src/main/java/com/correai/api/application/goal/GoalApplicationService.java`](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/goal/GoalApplicationService.java) (Goal workflow), [`src/main/java/com/correai/api/application/auth/AuthApplicationService.java`](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/auth/AuthApplicationService.java) (Anonymous auth), [`src/main/java/com/correai/api/adapter/in/web/config/UserContextInterceptor.java`](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/config/UserContextInterceptor.java) (User context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web API"]
  node_auth_web["Auth endpoint"]
  node_activity_web["Activity endpoints"]
  node_goal_web["Goal endpoints"]
  node_stats_web["Stats endpoints"]
  node_user_context["User context"]
end

subgraph group_app["Application workflows"]
  node_auth_service["Anonymous auth"]
  node_activity_service["Activity workflow"]
  node_goal_service["Goal workflow"]
  node_stats_service["Statistics workflow"]
  node_streak["Streak calculator"]
end

subgraph group_domain["Domain models"]
  node_activity_model["Activity model<br/>[Activity.java]"]
  node_goal_model["Goal model<br/>[Goal.java]"]
end

subgraph group_infra["Outbound adapters"]
  node_activity_persistence["Activity persistence"]
  node_goal_persistence["Goal persistence"]
  node_user_persistence["User persistence"]
  node_jwt_adapter["JWT adapter"]
end

node_client(("API client"))
node_database[("PostgreSQL")]

node_client -->|"requests token"| node_auth_web
node_auth_web -->|"issues token"| node_auth_service
node_auth_service -->|"saves user"| node_user_persistence
node_auth_service -->|"issues or verifies"| node_jwt_adapter
node_client -->|"sends requests"| node_activity_web
node_client -.->|"requests goals"| node_goal_web
node_client -->|"requests stats"| node_stats_web
node_activity_web -->|"receives user context"| node_user_context
node_stats_web -->|"receives user context"| node_user_context
node_goal_web -.->|"receives user context"| node_user_context
node_user_context -->|"authenticates token"| node_auth_service
node_activity_web -->|"invokes use cases"| node_activity_service
node_goal_web -->|"invokes use cases"| node_goal_service
node_stats_web -->|"invokes use cases"| node_stats_service
node_activity_service -->|"creates activities"| node_activity_model
node_activity_service -->|"calculates streak"| node_streak
node_stats_service -->|"calculates streak"| node_streak
node_goal_service -->|"creates or deactivates"| node_goal_model
node_activity_service -->|"uses repository port"| node_activity_persistence
node_goal_service -->|"uses repository port"| node_goal_persistence
node_goal_service -->|"reads activities"| node_activity_persistence
node_stats_service -->|"reads activities"| node_activity_persistence
node_activity_persistence -->|"reads and writes"| node_database
node_goal_persistence -->|"reads and writes"| node_database
node_user_persistence -->|"reads and writes"| node_database

click node_auth_web "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/auth/AuthController.java"
click node_activity_web "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/activity/ActivityController.java"
click node_goal_web "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/goal/GoalController.java"
click node_stats_web "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/stats/StatsController.java"
click node_user_context "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/config/UserContextInterceptor.java"
click node_auth_service "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/auth/AuthApplicationService.java"
click node_activity_service "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/activity/ActivityApplicationService.java"
click node_goal_service "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/goal/GoalApplicationService.java"
click node_stats_service "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/stats/StatsApplicationService.java"
click node_streak "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/common/StreakCalculator.java"
click node_activity_model "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/domain/model/activity/Activity.java"
click node_goal_model "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/domain/model/goal/Goal.java"
click node_activity_persistence "https://github.com/joabss/correai-api/tree/master/src/main/java/com/correai/api/adapter/out/persistence/activity"
click node_goal_persistence "https://github.com/joabss/correai-api/tree/master/src/main/java/com/correai/api/adapter/out/persistence/goal"
click node_user_persistence "https://github.com/joabss/correai-api/tree/master/src/main/java/com/correai/api/adapter/out/persistence/user"
click node_jwt_adapter "https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/out/security/JwtTokenAdapter.java"

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_auth_web,node_activity_web,node_goal_web,node_stats_web,node_user_context,node_client toneBlue
class node_auth_service,node_activity_service,node_goal_service,node_stats_service,node_streak,node_database toneAmber
class node_activity_model,node_goal_model toneMint
class node_activity_persistence,node_goal_persistence,node_user_persistence,node_jwt_adapter toneRose
```

## Components

### Web API

- [Auth endpoint](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/auth/AuthController.java): `src/main/java/com/correai/api/adapter/in/web/auth/AuthController.java`
- [Activity endpoints](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/activity/ActivityController.java): `src/main/java/com/correai/api/adapter/in/web/activity/ActivityController.java`
- [Goal endpoints](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/goal/GoalController.java): `src/main/java/com/correai/api/adapter/in/web/goal/GoalController.java`
- [Stats endpoints](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/stats/StatsController.java): `src/main/java/com/correai/api/adapter/in/web/stats/StatsController.java`
- [User context](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/in/web/config/UserContextInterceptor.java): `src/main/java/com/correai/api/adapter/in/web/config/UserContextInterceptor.java`

### Application workflows

- [Anonymous auth](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/auth/AuthApplicationService.java): `src/main/java/com/correai/api/application/auth/AuthApplicationService.java`
- [Activity workflow](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/activity/ActivityApplicationService.java): `src/main/java/com/correai/api/application/activity/ActivityApplicationService.java`
- [Goal workflow](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/goal/GoalApplicationService.java): `src/main/java/com/correai/api/application/goal/GoalApplicationService.java`
- [Statistics workflow](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/stats/StatsApplicationService.java): `src/main/java/com/correai/api/application/stats/StatsApplicationService.java`
- [Streak calculator](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/application/common/StreakCalculator.java): `src/main/java/com/correai/api/application/common/StreakCalculator.java`

### Domain models

- [Activity model](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/domain/model/activity/Activity.java): `src/main/java/com/correai/api/domain/model/activity/Activity.java`
- [Goal model](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/domain/model/goal/Goal.java): `src/main/java/com/correai/api/domain/model/goal/Goal.java`

### Outbound adapters

- [Activity persistence](https://github.com/joabss/correai-api/tree/master/src/main/java/com/correai/api/adapter/out/persistence/activity): `src/main/java/com/correai/api/adapter/out/persistence/activity`
- [Goal persistence](https://github.com/joabss/correai-api/tree/master/src/main/java/com/correai/api/adapter/out/persistence/goal): `src/main/java/com/correai/api/adapter/out/persistence/goal`
- [User persistence](https://github.com/joabss/correai-api/tree/master/src/main/java/com/correai/api/adapter/out/persistence/user): `src/main/java/com/correai/api/adapter/out/persistence/user`
- [JWT adapter](https://github.com/joabss/correai-api/blob/master/src/main/java/com/correai/api/adapter/out/security/JwtTokenAdapter.java): `src/main/java/com/correai/api/adapter/out/security/JwtTokenAdapter.java`

### Other components

- **API client**
- **PostgreSQL**

## Connections

- API client → Auth endpoint: requests token
- Auth endpoint → Anonymous auth: issues token (evidence: `src/main/java/com/correai/api/adapter/in/web/auth/AuthController.java`)
- Anonymous auth → User persistence: saves user
- Anonymous auth → JWT adapter: issues or verifies
- API client → Activity endpoints: sends requests
- API client → Goal endpoints: requests goals
- API client → Stats endpoints: requests stats
- Activity endpoints → User context: receives user context
- Stats endpoints → User context: receives user context
- Goal endpoints → User context: receives user context
- User context → Anonymous auth: authenticates token
- Activity endpoints → Activity workflow: invokes use cases
- Goal endpoints → Goal workflow: invokes use cases
- Stats endpoints → Statistics workflow: invokes use cases
- Activity workflow → Activity model: creates activities (evidence: `src/main/java/com/correai/api/domain/model/activity/Activity.java`)
- Activity workflow → Streak calculator: calculates streak (evidence: `src/main/java/com/correai/api/application/activity/ActivityApplicationService.java`)
- Statistics workflow → Streak calculator: calculates streak (evidence: `src/main/java/com/correai/api/application/stats/StatsApplicationService.java`)
- Goal workflow → Goal model: creates or deactivates (evidence: `src/main/java/com/correai/api/application/goal/GoalApplicationService.java`)
- Activity workflow → Activity persistence: uses repository port
- Goal workflow → Goal persistence: uses repository port
- Goal workflow → Activity persistence: reads activities
- Statistics workflow → Activity persistence: reads activities
- Activity persistence → PostgreSQL: reads and writes
- Goal persistence → PostgreSQL: reads and writes
- User persistence → PostgreSQL: reads and writes
