# fellias/satwa-lyar architecture

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

- Interactive diagram: https://gitdiagram.com/fellias/satwa-lyar
- Repository: https://github.com/fellias/satwa-lyar

## Overview

SATWA LYAR is a public fauna-learning site with an admin console, backed by an Express REST API. Visitors browse four fauna zones and animal details, save favorites, and take scored quizzes; admins manage fauna, categories, highlights, quizzes, users, and activity analytics. The API also supports guest identity, admin authentication, and request/activity logging. The README establishes the web/API split; dashed web-to-API links are architectural rather than verified call sites. Some unsampled controllers are represented from the tree and README, so their internal links are omitted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/app.ts) (Express application), [`apps/api/src/modules/logs/logs.service.ts`](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/logs/logs.service.ts) (Activity and audit logs), [`apps/api/src/modules/animals/animals.controller.ts`](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/animals/animals.controller.ts) (Animal catalog), [`apps/web/lib/api.ts`](https://github.com/fellias/satwa-lyar/blob/main/apps/web/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Next.js experience"]
  node_webapi["API client<br/>[api.ts]"]
  node_publicbrowse["Fauna exploration"]
  node_quizui["Quiz experience<br/>[page.tsx]"]
  node_adminui["Admin console"]
end

subgraph group_api["API entry and identity"]
  node_server["Express application<br/>[app.ts]"]
  node_identity["Guest and admin identity"]
  node_auth["Admin authentication<br/>[auth.controller.ts]"]
  node_profile["User profile"]
end

subgraph group_content["Fauna and learning"]
  node_animalapi["Animal catalog"]
  node_categoryapi["Fauna zones"]
  node_highlightapi["Featured animals"]
  node_favoriteapi["Favorites"]
  node_quizadmin["Quiz authoring<br/>[quiz.controller.ts]"]
  node_quizuser["Quiz results"]
end

subgraph group_admin["Administration and observability"]
  node_dashboard["Admin statistics"]
  node_usersadmin["Administrator management"]
  node_logs["Activity and audit logs<br/>[logs.service.ts]"]
  node_logreader["Log reader<br/>[logs.controller.ts]"]
end

node_visitor(("Visitor or admin"))
node_mariadb[("MariaDB")]
node_redis[("Redis cache<br/>[redis.ts]")]
node_r2[("Cloudflare R2<br/>[r2.ts]")]

node_visitor -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_webapi
node_webapi -.->|"calls REST API"| node_server
node_server -->|"installs middleware"| node_identity
node_server -->|"mounts routes"| node_auth
node_server -->|"mounts routes"| node_animalapi
node_server -->|"mounts routes"| node_categoryapi
node_server -->|"mounts routes"| node_favoriteapi
node_server -->|"mounts routes"| node_quizuser
node_server -->|"mounts routes"| node_quizadmin
node_server -->|"mounts routes"| node_profile
node_server -->|"mounts routes"| node_highlightapi
node_server -->|"mounts routes"| node_dashboard
node_server -->|"mounts routes"| node_usersadmin
node_server -->|"mounts routes"| node_logreader
node_animalapi -->|"queries"| node_mariadb
node_animalapi -->|"stores images"| node_r2
node_animalapi -->|"invalidates cache"| node_redis
node_animalapi -->|"records actions"| node_logs
node_categoryapi -->|"queries"| node_mariadb
node_categoryapi -->|"invalidates cache"| node_redis
node_categoryapi -->|"records actions"| node_logs
node_highlightapi -->|"queries"| node_mariadb
node_highlightapi -->|"invalidates cache"| node_redis
node_highlightapi -->|"records actions"| node_logs
node_favoriteapi -->|"reads and writes"| node_mariadb
node_quizadmin -->|"queries"| node_mariadb
node_quizadmin -->|"records actions"| node_logs
node_quizuser -->|"queries"| node_mariadb
node_quizuser -->|"records quiz events"| node_logs
node_auth -->|"queries"| node_mariadb
node_auth -->|"records activity"| node_logs
node_usersadmin -->|"queries"| node_mariadb
node_usersadmin -->|"records actions"| node_logs
node_dashboard -->|"queries"| node_mariadb
node_logreader -->|"reads logs"| node_mariadb
node_logs -->|"persists events"| node_mariadb
node_publicbrowse -.->|"uses client"| node_webapi
node_quizui -.->|"uses client"| node_webapi
node_adminui -.->|"uses client"| node_webapi

click node_webapp "https://github.com/fellias/satwa-lyar/tree/main/apps/web/app"
click node_webapi "https://github.com/fellias/satwa-lyar/blob/main/apps/web/lib/api.ts"
click node_publicbrowse "https://github.com/fellias/satwa-lyar/blob/main/apps/web/components/PublicAnimalExplorer.tsx"
click node_quizui "https://github.com/fellias/satwa-lyar/blob/main/apps/web/app/kuis/page.tsx"
click node_adminui "https://github.com/fellias/satwa-lyar/tree/main/apps/web/app/admin"
click node_server "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/app.ts"
click node_identity "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/middleware/guest-context.middleware.ts"
click node_auth "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_animalapi "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/animals/animals.controller.ts"
click node_categoryapi "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/categories/categories.controller.ts"
click node_highlightapi "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/highlights/highlights.controller.ts"
click node_favoriteapi "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/favorites/favorites.controller.ts"
click node_quizadmin "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/quiz/quiz.controller.ts"
click node_quizuser "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/quiz/quiz.user.controller.ts"
click node_profile "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/users/users.profile.controller.ts"
click node_dashboard "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/dashboard/dashboard.controller.ts"
click node_usersadmin "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/users/users.controller.ts"
click node_logs "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/logs/logs.service.ts"
click node_logreader "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/logs/logs.controller.ts"
click node_redis "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/config/redis.ts"
click node_r2 "https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/config/r2.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_webapp,node_webapi,node_publicbrowse,node_quizui,node_adminui toneBlue
class node_server,node_identity,node_auth,node_profile,node_mariadb,node_redis,node_r2 toneAmber
class node_animalapi,node_categoryapi,node_highlightapi,node_favoriteapi,node_quizadmin,node_quizuser toneMint
class node_dashboard,node_usersadmin,node_logs,node_logreader toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Next.js experience](https://github.com/fellias/satwa-lyar/tree/main/apps/web/app): `apps/web/app`
- [API client](https://github.com/fellias/satwa-lyar/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`
- [Fauna exploration](https://github.com/fellias/satwa-lyar/blob/main/apps/web/components/PublicAnimalExplorer.tsx): `apps/web/components/PublicAnimalExplorer.tsx`
- [Quiz experience](https://github.com/fellias/satwa-lyar/blob/main/apps/web/app/kuis/page.tsx): `apps/web/app/kuis/page.tsx`
- [Admin console](https://github.com/fellias/satwa-lyar/tree/main/apps/web/app/admin): `apps/web/app/admin`

### API entry and identity

- [Express application](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Guest and admin identity](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/middleware/guest-context.middleware.ts): `apps/api/src/middleware/guest-context.middleware.ts`
- [Admin authentication](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [User profile](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/users/users.profile.controller.ts): `apps/api/src/modules/users/users.profile.controller.ts`

### Fauna and learning

- [Animal catalog](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/animals/animals.controller.ts): `apps/api/src/modules/animals/animals.controller.ts`
- [Fauna zones](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/categories/categories.controller.ts): `apps/api/src/modules/categories/categories.controller.ts`
- [Featured animals](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/highlights/highlights.controller.ts): `apps/api/src/modules/highlights/highlights.controller.ts`
- [Favorites](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/favorites/favorites.controller.ts): `apps/api/src/modules/favorites/favorites.controller.ts`
- [Quiz authoring](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/quiz/quiz.controller.ts): `apps/api/src/modules/quiz/quiz.controller.ts`
- [Quiz results](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/quiz/quiz.user.controller.ts): `apps/api/src/modules/quiz/quiz.user.controller.ts`

### Administration and observability

- [Admin statistics](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/dashboard/dashboard.controller.ts): `apps/api/src/modules/dashboard/dashboard.controller.ts`
- [Administrator management](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/users/users.controller.ts): `apps/api/src/modules/users/users.controller.ts`
- [Activity and audit logs](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/logs/logs.service.ts): `apps/api/src/modules/logs/logs.service.ts`
- [Log reader](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/modules/logs/logs.controller.ts): `apps/api/src/modules/logs/logs.controller.ts`

### Other components

- **Visitor or admin**
- **MariaDB**
- [Redis cache](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/config/redis.ts): `apps/api/src/config/redis.ts`
- [Cloudflare R2](https://github.com/fellias/satwa-lyar/blob/main/apps/api/src/config/r2.ts): `apps/api/src/config/r2.ts`

## Connections

- Visitor or admin → Next.js experience: uses (evidence: `README.md`)
- Next.js experience → API client: requests data
- API client → Express application: calls REST API
- Express application → Guest and admin identity: installs middleware (evidence: `apps/api/src/app.ts`)
- Express application → Admin authentication: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Animal catalog: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Fauna zones: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Favorites: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Quiz results: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Quiz authoring: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → User profile: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Featured animals: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Admin statistics: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Administrator management: mounts routes (evidence: `apps/api/src/app.ts`)
- Express application → Log reader: mounts routes (evidence: `apps/api/src/app.ts`)
- Animal catalog → MariaDB: queries (evidence: `apps/api/src/modules/animals/animals.controller.ts`)
- Animal catalog → Cloudflare R2: stores images (evidence: `apps/api/src/modules/animals/animals.controller.ts`)
- Animal catalog → Redis cache: invalidates cache (evidence: `apps/api/src/modules/animals/animals.controller.ts`)
- Animal catalog → Activity and audit logs: records actions (evidence: `apps/api/src/modules/animals/animals.controller.ts`)
- Fauna zones → MariaDB: queries (evidence: `apps/api/src/modules/categories/categories.controller.ts`)
- Fauna zones → Redis cache: invalidates cache (evidence: `apps/api/src/modules/categories/categories.controller.ts`)
- Fauna zones → Activity and audit logs: records actions (evidence: `apps/api/src/modules/categories/categories.controller.ts`)
- Featured animals → MariaDB: queries (evidence: `apps/api/src/modules/highlights/highlights.controller.ts`)
- Featured animals → Redis cache: invalidates cache (evidence: `apps/api/src/modules/highlights/highlights.controller.ts`)
- Featured animals → Activity and audit logs: records actions (evidence: `apps/api/src/modules/highlights/highlights.controller.ts`)
- Favorites → MariaDB: reads and writes (evidence: `apps/api/src/modules/favorites/favorites.controller.ts`)
- Quiz authoring → MariaDB: queries (evidence: `apps/api/src/modules/quiz/quiz.controller.ts`)
- Quiz authoring → Activity and audit logs: records actions (evidence: `apps/api/src/modules/quiz/quiz.controller.ts`)
- Quiz results → MariaDB: queries (evidence: `apps/api/src/modules/quiz/quiz.user.controller.ts`)
- Quiz results → Activity and audit logs: records quiz events (evidence: `apps/api/src/modules/quiz/quiz.user.controller.ts`)
- Admin authentication → MariaDB: queries (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Admin authentication → Activity and audit logs: records activity (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Administrator management → MariaDB: queries (evidence: `apps/api/src/modules/users/users.controller.ts`)
- Administrator management → Activity and audit logs: records actions (evidence: `apps/api/src/modules/users/users.controller.ts`)
- Admin statistics → MariaDB: queries (evidence: `apps/api/src/modules/dashboard/dashboard.controller.ts`)
- Log reader → MariaDB: reads logs (evidence: `apps/api/src/modules/logs/logs.controller.ts`)
- Activity and audit logs → MariaDB: persists events (evidence: `apps/api/src/modules/logs/logs.service.ts`)
- Fauna exploration → API client: uses client
- Quiz experience → API client: uses client
- Admin console → API client: uses client