# afloresc/atutorgobknd architecture

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

- Interactive diagram: https://gitdiagram.com/afloresc/atutorgobknd
- Repository: https://github.com/afloresc/atutorgobknd

## Overview

#### Purpose and Entry Points
This is a Go backend for ATutor, managing course lessons and related learning data for an Android client. The executable entry point is `domain/cmd/main.go`; runtime configuration is represented by `domain/cmd/app.yaml` and environment files such as `.env`.

#### Application Composition
`controller/application.go` is the central application/controller assembly point. It likely binds HTTP transport, domain operations, configuration, and service dependencies into the running backend. `domain/cmd/main.go` starts that application, making the `domain/cmd` package the deployment boundary.

#### Domain Model
The `domain` package defines the backend’s core learning and identity model:
- Course and lesson hierarchy: `domain/course.go`, `domain/lesson.go`, `domain/content.go`.
- Learning structure and assessments: `domain/concept.go`, `domain/question.go`, `domain/questionary.go`.
- Student progress and outcomes: `domain/user_lesson.go`, `domain/marks.go`, `domain/report.go`.
- Users, clients, and roles: `domain/user.go`, `domain/client.go`, `domain/roles.go`.

These domain types form the primary data contract between controllers, authorization, and persistence/service integrations.

#### HTTP and Response Boundary
`ahttp/responsemanager.go` centralizes HTTP response handling, likely including consistent success/error serialization and status mapping. The controller layer in `controller/application.go` is the likely request-routing and use-case boundary; it should translate incoming HTTP requests into domain operations and return responses through `ahttp`.

#### Authentication and Authorization
JWT authentication and role-based access control are isolated under `tapi/rbac`:
- JWT middleware: `tapi/rbac/jwtmiddleware.go`.
- Token creation/validation: `tapi/rbac/token.go`.
- Authorization decisions and role definitions: `tapi/rbac/rbac.go`, `tapi/rbac/roles.go`.

This establishes a security boundary before protected course, lesson, user-progress, and assessment operations execute. `domain/jwt.go` and `domain/roles.go` provide related domain-level identity/security representations.

#### Configuration and Runtime Dependencies
Configuration is modeled in `domain/config.go`, loaded with environment support from `utils/env.go`, and supplied at startup from `domain/cmd/main.go`. The repository does not expose a distinct database adapter or external SaaS client in the provided tree; persistence and remote-service behavior, if present, is likely encapsulated behind domain/client abstractions such as `domain/client.go`.

#### Primary Flow
A client request enters the application assembled by `controller/application.go`; protected routes pass through `tapi/rbac/jwtmiddleware.go`, where JWT identity and RBAC permissions are evaluated. Authorized handlers operate on course/lesson/content, assessments, or user-progress domain entities. Results and failures cross the HTTP boundary through `ahttp/responsemanager.go`, with shared error behavior from `utils/errors.go`.

Main entry points: [`controller/application.go`](https://github.com/afloresc/atutorgobknd/blob/master/controller/application.go) (Application assembly), [`domain/cmd/main.go`](https://github.com/afloresc/atutorgobknd/blob/master/domain/cmd/main.go) (Backend entry point), [`tapi/rbac/jwtmiddleware.go`](https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/jwtmiddleware.go) (JWT middleware), [`tapi/rbac/rbac.go`](https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/rbac.go) (Authorization rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Backend entry point<br/>Go executable<br/>[main.go]"]
  node_runtime_config["Runtime configuration<br/>[app.yaml]"]
  node_config["Configuration model<br/>domain config<br/>[config.go]"]
  node_env["Environment loader<br/>[env.go]"]
end

subgraph group_transport["HTTP Application"]
  node_application["Application assembly<br/>controller<br/>[application.go]"]
  node_response_manager["Response manager<br/>HTTP response boundary<br/>[responsemanager.go]"]
  node_errors["Shared errors<br/>[errors.go]"]
end

subgraph group_security["Authentication &amp; RBAC"]
  node_jwt_middleware["JWT middleware<br/>HTTP middleware<br/>[jwtmiddleware.go]"]
  node_token["JWT tokens<br/>token service<br/>[token.go]"]
  node_rbac["Authorization rules<br/>RBAC service<br/>[rbac.go]"]
  node_rbac_roles["RBAC roles<br/>role definitions<br/>[roles.go]"]
end

subgraph group_domain["Learning Domain"]
  node_learning["Course learning model<br/>domain model<br/>[course.go]"]
  node_assessment["Assessment model<br/>domain model<br/>[question.go]"]
  node_progress["Progress and outcomes<br/>domain model<br/>[user_lesson.go]"]
  node_identity["Users and clients<br/>domain model<br/>[user.go]"]
  node_domain_jwt["Domain JWT identity<br/>domain model<br/>[jwt.go]"]
  node_domain_roles["Domain roles<br/>domain model<br/>[roles.go]"]
end

node_main -->|"loads"| node_runtime_config
node_main -->|"reads"| node_env
node_runtime_config -->|"populates"| node_config
node_env -->|"overrides"| node_config
node_main -->|"starts"| node_application
node_config -->|"supplies"| node_application
node_application -->|"protected requests"| node_jwt_middleware
node_jwt_middleware -->|"validates"| node_token
node_jwt_middleware -->|"authorizes via"| node_rbac
node_rbac -->|"uses"| node_rbac_roles
node_token -->|"maps identity"| node_domain_jwt
node_rbac -->|"maps roles"| node_domain_roles
node_application -->|"handles"| node_learning
node_application -->|"handles"| node_assessment
node_application -->|"handles"| node_progress
node_application -->|"handles"| node_identity
node_application -->|"returns via"| node_response_manager
node_response_manager -->|"maps"| node_errors
node_progress -.->|"tracks"| node_learning
node_assessment -.->|"belongs to"| node_learning
node_identity -.->|"owns"| node_progress

click node_main "https://github.com/afloresc/atutorgobknd/blob/master/domain/cmd/main.go"
click node_runtime_config "https://github.com/afloresc/atutorgobknd/blob/master/domain/cmd/app.yaml"
click node_config "https://github.com/afloresc/atutorgobknd/blob/master/domain/config.go"
click node_env "https://github.com/afloresc/atutorgobknd/blob/master/utils/env.go"
click node_application "https://github.com/afloresc/atutorgobknd/blob/master/controller/application.go"
click node_response_manager "https://github.com/afloresc/atutorgobknd/blob/master/ahttp/responsemanager.go"
click node_errors "https://github.com/afloresc/atutorgobknd/blob/master/utils/errors.go"
click node_jwt_middleware "https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/jwtmiddleware.go"
click node_token "https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/token.go"
click node_rbac "https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/rbac.go"
click node_rbac_roles "https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/roles.go"
click node_learning "https://github.com/afloresc/atutorgobknd/blob/master/domain/course.go"
click node_assessment "https://github.com/afloresc/atutorgobknd/blob/master/domain/question.go"
click node_progress "https://github.com/afloresc/atutorgobknd/blob/master/domain/user_lesson.go"
click node_identity "https://github.com/afloresc/atutorgobknd/blob/master/domain/user.go"
click node_domain_jwt "https://github.com/afloresc/atutorgobknd/blob/master/domain/jwt.go"
click node_domain_roles "https://github.com/afloresc/atutorgobknd/blob/master/domain/roles.go"

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_main,node_runtime_config,node_config,node_env toneBlue
class node_application,node_response_manager,node_errors toneAmber
class node_jwt_middleware,node_token,node_rbac,node_rbac_roles toneMint
class node_learning,node_assessment,node_progress,node_identity,node_domain_jwt,node_domain_roles toneRose
```

## Components

### Runtime

- [Backend entry point](https://github.com/afloresc/atutorgobknd/blob/master/domain/cmd/main.go): Go executable · Starts the configured backend. · `domain/cmd/main.go`
- [Runtime configuration](https://github.com/afloresc/atutorgobknd/blob/master/domain/cmd/app.yaml): config · `domain/cmd/app.yaml`
- [Configuration model](https://github.com/afloresc/atutorgobknd/blob/master/domain/config.go): domain config · `domain/config.go`
- [Environment loader](https://github.com/afloresc/atutorgobknd/blob/master/utils/env.go): utility · `utils/env.go`

### HTTP Application

- [Application assembly](https://github.com/afloresc/atutorgobknd/blob/master/controller/application.go): controller · Composes transport, security, and domain dependencies. · `controller/application.go`
- [Response manager](https://github.com/afloresc/atutorgobknd/blob/master/ahttp/responsemanager.go): HTTP response boundary · Serializes success and error responses. · `ahttp/responsemanager.go`
- [Shared errors](https://github.com/afloresc/atutorgobknd/blob/master/utils/errors.go): utility · `utils/errors.go`

### Authentication & RBAC

- [JWT middleware](https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/jwtmiddleware.go): HTTP middleware · Protects routes and establishes request identity. · `tapi/rbac/jwtmiddleware.go`
- [JWT tokens](https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/token.go): token service · Creates and validates JWTs. · `tapi/rbac/token.go`
- [Authorization rules](https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/rbac.go): RBAC service · Evaluates role permissions. · `tapi/rbac/rbac.go`
- [RBAC roles](https://github.com/afloresc/atutorgobknd/blob/master/tapi/rbac/roles.go): role definitions · `tapi/rbac/roles.go`

### Learning Domain

- [Course learning model](https://github.com/afloresc/atutorgobknd/blob/master/domain/course.go): domain model · Courses, lessons, content, and concepts. · `domain/course.go`
- [Assessment model](https://github.com/afloresc/atutorgobknd/blob/master/domain/question.go): domain model · Questions and questionnaires. · `domain/question.go`
- [Progress and outcomes](https://github.com/afloresc/atutorgobknd/blob/master/domain/user_lesson.go): domain model · User lessons, marks, and reports. · `domain/user_lesson.go`
- [Users and clients](https://github.com/afloresc/atutorgobknd/blob/master/domain/user.go): domain model · Users, client abstractions, and roles. · `domain/user.go`
- [Domain JWT identity](https://github.com/afloresc/atutorgobknd/blob/master/domain/jwt.go): domain model · `domain/jwt.go`
- [Domain roles](https://github.com/afloresc/atutorgobknd/blob/master/domain/roles.go): domain model · `domain/roles.go`

## Connections

- Backend entry point → Runtime configuration: loads
- Backend entry point → Environment loader: reads
- Runtime configuration → Configuration model: populates
- Environment loader → Configuration model: overrides
- Backend entry point → Application assembly: starts
- Configuration model → Application assembly: supplies
- Application assembly → JWT middleware: protected requests
- JWT middleware → JWT tokens: validates
- JWT middleware → Authorization rules: authorizes via
- Authorization rules → RBAC roles: uses
- JWT tokens → Domain JWT identity: maps identity
- Authorization rules → Domain roles: maps roles
- Application assembly → Course learning model: handles
- Application assembly → Assessment model: handles
- Application assembly → Progress and outcomes: handles
- Application assembly → Users and clients: handles
- Application assembly → Response manager: returns via
- Response manager → Shared errors: maps
- Progress and outcomes → Course learning model: tracks
- Assessment model → Course learning model: belongs to
- Users and clients → Progress and outcomes: owns