onasty: docs/Architecture.md (e73c44f)

1

# Architecture

2

3

## Project structure

4

```bash

5

├── api/             # OpenAPI spec for the backend

6

├── cmd/

7

│   ├── api          # Entry point for the backend app

8

│   └── seed         # Entry point for the db seed app, useful during development

9

├── deploy/          # All stuff related to deployment of this app

10

├── docs/            # You're here, and reading the docs :D

11

├── e2e/             # E2E tests for the API (go)

12

├── go.mod

13

├── go.sum

14

├── infra/           # Configurations for infrastructure(grafana, loki, prometheus, caddy)

15

├── internal/        # The core application (go)

16

│   ├── config       # > app config duh

17

│   ├── dtos         # > data transfer objects

18

│   ├── events       # > message publishing

19

│   ├── hasher       # > general interface to work with hash

20

│   ├── jwtutil      # > jwt token helpers

21

│   ├── logger       # > log/slog configuration

22

│   ├── metrics      # > Prometheus metrics

23

│   ├── models       # > domain entities

24

│   ├── oauth        # > interface to work with OAuth2 providers

25

│   ├── service      # > business logic (auth, notes, users

26

│   ├── store        # > persistence layer(postgres, redis)

27

│   └── transport    # > transport layer(http handlers)

28

├── mailer/          # mailer service (go)

29

├── migrations/      # DB migrations live here (sql)

30

├── Taskfile.yml     # task file with all tasks for the app development

31

└── web/             # The frontend app (elm)

32

    ├── review       # > elm-review configuration

33

    ├── static       # > all static file(images, fonts, styles, etc)

34

    ├── src

35

    └── tests

36

```

37

38

## Data flow

39

1. Frontend/Api -> Backend

40

  - The Elm frontend ([web/](/web)) sends requests to the backend API.

41

2. Transport layer (http handlers)

42

  - User provided data gets mapped into DTO and passed to service layer.

43

  - DTOs are only used between transport and services; the rest of the application uses domain models.

44

3. Business logic (services)

45

  - Services receive DTOs, map them into domain models, and implement the use case (auth, notes, users).

46

  - Services may interact with:

47

    - Persistence (store → Postgres, Redis)

48

    - Events (events → NATS)

49

    - Utilities (`jwtutil`, `hasher`)

50

4. Persistence

51

  - Postgres stores durable data (users, notes).

52

  - Redis handles caching/ephemeral state.

53

5. Background tasks (fire-and-forget)

54

  - Some operations, like sending verification emails, are published as NATS events.

55

6. Response

56

  - After business logic is complete, domain models are mapped back to DTOs, and returned via transport layer.

57

  - Elm frontend updates the UI accordingly.

58

7. Observability

59

  - Services log via logger and export Prometheus metrics (`metrics`).

60

  - Grafana, Loki, and Prometheus provide monitoring.

61

62

## Docker

63

The project uses multiple Dockerfiles with a multi-stage build approach:

64

- `builder.Dockerfile` – builds Go binaries and caches dependencies.

65

- `runtime.Dockerfile` – lightweight Alpine base image with system packages preinstalled (used by app images to speed up builds).

66

- `core.Dockerfile` – packages the main backend API service.

67

- `mailer.Dockerfile` – packages the mailer service.

68

69

## Services

70

- Core service (go)

71

  - Exposes RestAPI (see. [API](/docs/API.md))

72

  - Handles authentication

73

  - Manages notes life cycle

74

- Mailer

75

  - Listens for events from the core.

76

  - Sends account confirmation and password reset emails.

77

  - Provides its own Prometheus metrics.

78

  - **NOTE:** all events of the service is documented [here](/mailer/)

79

80

## Frontend

81

- Built with [elm.land](https://elm.land)

82

- Uses elm-review rules for consistency and quality.

83

- Compiled into a static bundle (web/dist), served by Caddy.

1	# Architecture
2
3	## Project structure
4	```bash
5	├── api/ # OpenAPI spec for the backend
6	├── cmd/
7	│ ├── api # Entry point for the backend app
8	│ └── seed # Entry point for the db seed app, useful during development
9	├── deploy/ # All stuff related to deployment of this app
10	├── docs/ # You're here, and reading the docs :D
11	├── e2e/ # E2E tests for the API (go)
12	├── go.mod
13	├── go.sum
14	├── infra/ # Configurations for infrastructure(grafana, loki, prometheus, caddy)
15	├── internal/ # The core application (go)
16	│ ├── config # > app config duh
17	│ ├── dtos # > data transfer objects
18	│ ├── events # > message publishing
19	│ ├── hasher # > general interface to work with hash
20	│ ├── jwtutil # > jwt token helpers
21	│ ├── logger # > log/slog configuration
22	│ ├── metrics # > Prometheus metrics
23	│ ├── models # > domain entities
24	│ ├── oauth # > interface to work with OAuth2 providers
25	│ ├── service # > business logic (auth, notes, users
26	│ ├── store # > persistence layer(postgres, redis)
27	│ └── transport # > transport layer(http handlers)
28	├── mailer/ # mailer service (go)
29	├── migrations/ # DB migrations live here (sql)
30	├── Taskfile.yml # task file with all tasks for the app development
31	└── web/ # The frontend app (elm)
32	├── review # > elm-review configuration
33	├── static # > all static file(images, fonts, styles, etc)
34	├── src
35	└── tests
36	```
37
38	## Data flow
39	1. Frontend/Api -> Backend
40	- The Elm frontend ([web/](/web)) sends requests to the backend API.
41	2. Transport layer (http handlers)
42	- User provided data gets mapped into DTO and passed to service layer.
43	- DTOs are only used between transport and services; the rest of the application uses domain models.
44	3. Business logic (services)
45	- Services receive DTOs, map them into domain models, and implement the use case (auth, notes, users).
46	- Services may interact with:
47	- Persistence (store → Postgres, Redis)
48	- Events (events → NATS)
49	- Utilities (`jwtutil`, `hasher`)
50	4. Persistence
51	- Postgres stores durable data (users, notes).
52	- Redis handles caching/ephemeral state.
53	5. Background tasks (fire-and-forget)
54	- Some operations, like sending verification emails, are published as NATS events.
55	6. Response
56	- After business logic is complete, domain models are mapped back to DTOs, and returned via transport layer.
57	- Elm frontend updates the UI accordingly.
58	7. Observability
59	- Services log via logger and export Prometheus metrics (`metrics`).
60	- Grafana, Loki, and Prometheus provide monitoring.
61
62	## Docker
63	The project uses multiple Dockerfiles with a multi-stage build approach:
64	- `builder.Dockerfile` – builds Go binaries and caches dependencies.
65	- `runtime.Dockerfile` – lightweight Alpine base image with system packages preinstalled (used by app images to speed up builds).
66	- `core.Dockerfile` – packages the main backend API service.
67	- `mailer.Dockerfile` – packages the mailer service.
68
69	## Services
70	- Core service (go)
71	- Exposes RestAPI (see. [API](/docs/API.md))
72	- Handles authentication
73	- Manages notes life cycle
74	- Mailer
75	- Listens for events from the core.
76	- Sends account confirmation and password reset emails.
77	- Provides its own Prometheus metrics.
78	- NOTE: all events of the service is documented [here](/mailer/)
79
80	## Frontend
81	- Built with [elm.land](https://elm.land)
82	- Uses elm-review rules for consistency and quality.
83	- Compiled into a static bundle (web/dist), served by Caddy.