# artjansentec/atlasknowledgeapi architecture

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

- Interactive diagram: https://gitdiagram.com/artjansentec/atlasknowledgeapi
- Repository: https://github.com/artjansentec/atlasknowledgeapi

## Overview

1. **What this repository is**
   - `Atlas Knowledge API` is a Go REST backend for an internal knowledge wiki.
   - The core runtime is an HTTP API built with **Echo**, backed by **PostgreSQL**, using **JWT** auth, local file storage for uploads, and **OpenAPI/Swagger** for interactive docs.

2. **Top-level execution model**
   - The repo is organized around three runnable entrypoints in `cmd/`:
     - `cmd/api` starts the HTTP server.
     - `cmd/migrate` applies database migrations.
     - `cmd/create-admin` bootstraps the first admin user.
   - That separation is important architecturally: web serving, schema evolution, and bootstrap/admin provisioning are distinct processes.

3. **Request pipeline**
   - Incoming HTTP requests enter Echo handlers in `internal/handler/`.
   - Middleware in `internal/middleware/` performs auth checks and request context setup before handlers call services.
   - Handlers are thin: they validate/parse inputs, call the service layer, and convert results/errors into HTTP responses.

4. **Business logic boundary**
   - `internal/service/` contains the main business rules and orchestration.
   - This layer enforces permissions, coordinates multi-step operations, and combines database operations with file storage when needed.
   - Key services map directly to functional domains: `auth`, `user`, `project`, `section`, `lesson`, `attachment`, `search`.

5. **Persistence boundary**
   - `internal/repository/` is the data-access layer.
   - Repositories encapsulate Postgres queries for users, projects, sections, lessons, tags, audit records, files, and search-related operations.
   - `internal/db/` owns the database connection and migration bootstrap; `internal/db/migrations/` holds the schema definition and evolution history.

6. **Domain model**
   - `internal/domain/models.go` defines the core entities shared across layers.
   - The domain revolves around knowledge-content structures: users, projects, sections, lessons, attachments, tags, permissions, and related metadata.
   - This domain is the backbone for both API responses and internal service/repository contracts.

7. **Content hierarchy and access control**
   - The main business object is a **project**, which contains **sections**, which contain **lessons**.
   - Routes and services show hierarchical operations like create/update/delete/reorder for sections and lessons under a project slug.
   - Access is permissioned: there is admin-only project creation/deletion, reader assignment, and authenticated access to most resources.

8. **Authentication and session flow**
   - `internal/service/auth_service.go` and `internal/handler/auth_handler.go` implement login, token refresh, logout, and current-user lookup.
   - JWT uses HS256 with access/refresh TTLs from configuration.
   - Refresh flow uses cookies, while API calls use `Authorization: Bearer ...`, which creates two distinct auth channels.

9. **File attachment flow**
   - Attachments are a separate subsystem split between metadata and physical storage.
   - `internal/storage/file_storage.go` handles local filesystem persistence under `STORAGE_PATH`.
   - `internal/repository/file_repo.go` likely stores attachment metadata in Postgres, while `attachment_service.go` coordinates upload, download, and delete behavior.

10. **Search and read-model features**
   - `internal/service/search_service.go` and `internal/handler/search_handler.go` provide keyword search across the knowledge base.
   - Supporting repository utilities such as `search_util.go`, `tag_repo.go`, and `audit_repo.go` suggest search and dashboard views are built from aggregated database queries rather than a separate search engine.

11. **API presentation layer**
   - `internal/handler/` contains one handler per functional area: auth, health, project, section, lesson, attachment, search, and likely user/dashboard-related endpoints.
   - `internal/mapper/` converts between domain objects and response shapes, keeping HTTP contracts separate from internal models.
   - `internal/handler/response.go` and `pkg/httperr` standardize JSON responses and error handling.

12. **Validation and cross-cutting utilities**
   - `pkg/validator/` centralizes request validation.
   - `internal/service/permission.go` isolates authorization rules from the rest of the business logic.
   - `internal/repository/date_range.go` and related helpers indicate query logic is shared for filters and reporting-style endpoints.

13. **Documentation and developer experience**
   - The repo bundles its API contract in `internal/handler/openapi.yaml` and serves Swagger UI assets from `internal/handler/web/swagger-ui/`.
   - The README’s `/swagger` flow and the included `openapi.yaml` mean the API contract is a first-class part of the architecture, not an afterthought.

14. **Operational/deployment shape**
   - Configuration is env-driven through `internal/config/`, with key runtime settings for port, DB URL, JWT secrets, upload path, CORS, and file size limits.
   - The presence of PowerShell scripts and a Makefile suggests the project is intended for local developer execution as well as scripted setup.
   - Overall, this is a single-process REST backend with clear internal layering: HTTP → service → repository/storage → PostgreSQL/filesystem.

Main entry points: [`internal/handler`](https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/handler) (Handlers), [`internal/repository`](https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/repository) (Repositories), [`internal/domain/models.go`](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/domain/models.go) (Domain models), [`cmd/api/main.go`](https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/api/main.go) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cmd["Entry points"]
  node_cmd_api["API server<br/>Go main<br/>[main.go]"]
  node_cmd_migrate["Migrate<br/>Go main<br/>[main.go]"]
  node_cmd_admin["Create admin<br/>Go main<br/>[main.go]"]
end

subgraph group_grp_http["HTTP layer"]
  node_handler_pkg["Handlers<br/>HTTP endpoints"]
  node_middleware_auth["Auth middleware<br/>request middleware<br/>[auth.go]"]
  node_mapper_pkg["Mappers<br/>response mapping"]
  node_openapi_doc["OpenAPI docs<br/>API contract<br/>[openapi.yaml]"]
end

subgraph group_grp_core["Core domain"]
  node_auth_service["Auth<br/>[auth_service.go]"]
  node_project_service["Projects<br/>[project_service.go]"]
  node_section_service["Sections<br/>[section_service.go]"]
  node_lesson_service["Lessons<br/>[lesson_service.go]"]
  node_attachment_service["Attachments"]
  node_search_service["Search<br/>[search_service.go]"]
  node_user_service["Users<br/>[user_service.go]"]
  node_domain_models["Domain models<br/>entities<br/>[models.go]"]
end

subgraph group_grp_data["Data layer"]
  node_db_conn[("Database<br/>Postgres access<br/>[db.go]")]
  node_repositories["Repositories<br/>data access"]
  node_file_storage["File storage<br/>filesystem store<br/>[file_storage.go]"]
end

subgraph group_grp_shared["Shared packages"]
  node_validator_pkg["Validator<br/>input validation<br/>[validator.go]"]
  node_httperr_pkg["HTTP errors<br/>error mapping<br/>[errors.go]"]
end

node_cmd_api -->|"serves"| node_handler_pkg
node_cmd_api -->|"uses"| node_middleware_auth
node_cmd_api -->|"connects"| node_db_conn
node_cmd_api -->|"publishes"| node_openapi_doc
node_cmd_migrate -->|"migrates"| node_db_conn
node_cmd_admin -->|"bootstraps"| node_user_service
node_handler_pkg -->|"calls"| node_auth_service
node_handler_pkg -->|"calls"| node_project_service
node_handler_pkg -->|"calls"| node_section_service
node_handler_pkg -->|"calls"| node_lesson_service
node_handler_pkg -->|"calls"| node_attachment_service
node_handler_pkg -->|"calls"| node_search_service
node_handler_pkg -->|"calls"| node_user_service
node_handler_pkg -->|"validates"| node_validator_pkg
node_handler_pkg -->|"formats"| node_httperr_pkg
node_handler_pkg -->|"maps"| node_mapper_pkg
node_auth_service -->|"reads/writes"| node_repositories
node_project_service -->|"reads/writes"| node_repositories
node_section_service -->|"reads/writes"| node_repositories
node_lesson_service -->|"reads/writes"| node_repositories
node_attachment_service -->|"reads/writes"| node_repositories
node_attachment_service -->|"stores files"| node_file_storage
node_search_service -->|"queries"| node_repositories
node_user_service -->|"reads/writes"| node_repositories
node_repositories -->|"uses"| node_db_conn
node_repositories -->|"maps"| node_domain_models
node_mapper_pkg -->|"maps"| node_domain_models
node_auth_service -->|"uses"| node_domain_models
node_project_service -->|"uses"| node_domain_models
node_section_service -->|"uses"| node_domain_models
node_lesson_service -->|"uses"| node_domain_models
node_attachment_service -->|"uses"| node_domain_models
node_search_service -->|"uses"| node_domain_models

click node_cmd_api "https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/api/main.go"
click node_cmd_migrate "https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/migrate/main.go"
click node_cmd_admin "https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/create-admin/main.go"
click node_handler_pkg "https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/handler"
click node_middleware_auth "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/middleware/auth.go"
click node_mapper_pkg "https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/mapper"
click node_openapi_doc "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/handler/openapi.yaml"
click node_auth_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/auth_service.go"
click node_project_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/project_service.go"
click node_section_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/section_service.go"
click node_lesson_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/lesson_service.go"
click node_attachment_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/attachment_service.go"
click node_search_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/search_service.go"
click node_user_service "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/user_service.go"
click node_domain_models "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/domain/models.go"
click node_db_conn "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/db/db.go"
click node_repositories "https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/repository"
click node_file_storage "https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/storage/file_storage.go"
click node_validator_pkg "https://github.com/artjansentec/atlasknowledgeapi/blob/main/pkg/validator/validator.go"
click node_httperr_pkg "https://github.com/artjansentec/atlasknowledgeapi/blob/main/pkg/httperr/errors.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_cmd_api,node_cmd_migrate,node_cmd_admin toneBlue
class node_handler_pkg,node_middleware_auth,node_mapper_pkg,node_openapi_doc toneAmber
class node_auth_service,node_project_service,node_section_service,node_lesson_service,node_attachment_service,node_search_service,node_user_service,node_domain_models toneMint
class node_db_conn,node_repositories,node_file_storage toneRose
class node_validator_pkg,node_httperr_pkg toneIndigo
```

## Components

### Entry points

Runnable processes for serving the API, running migrations, and bootstrapping admin access.

- [API server](https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/api/main.go): Go main · Starts the Echo HTTP API process. · `cmd/api/main.go`
- [Migrate](https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/migrate/main.go): Go main · Applies database schema migrations. · `cmd/migrate/main.go`
- [Create admin](https://github.com/artjansentec/atlasknowledgeapi/blob/main/cmd/create-admin/main.go): Go main · Bootstraps the first admin user. · `cmd/create-admin/main.go`

### HTTP layer

Echo handlers, middleware, mappers, and API presentation assets.

- [Handlers](https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/handler): HTTP endpoints · Route handlers for auth, health, projects, sections, lessons, attachments, and search. · `internal/handler`
- [Auth middleware](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/middleware/auth.go): request middleware · JWT and request-context middleware for protected routes. · `internal/middleware/auth.go`
- [Mappers](https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/mapper): response mapping · Converts domain objects into API response shapes. · `internal/mapper`
- [OpenAPI docs](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/handler/openapi.yaml): API contract · Swagger/OpenAPI definition and embedded docs assets. · `internal/handler/openapi.yaml`

### Core domain

Business services and shared domain models.

- [Auth](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/auth_service.go): service · Login, refresh, logout, and current-user flow. · `internal/service/auth_service.go`
- [Projects](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/project_service.go): service · Project lifecycle, permissions, and hierarchy orchestration. · `internal/service/project_service.go`
- [Sections](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/section_service.go): service · Section CRUD and ordering within projects. · `internal/service/section_service.go`
- [Lessons](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/lesson_service.go): service · Lesson CRUD and content updates under sections. · `internal/service/lesson_service.go`
- [Attachments](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/attachment_service.go): service · Coordinates upload, download, metadata, and deletion. · `internal/service/attachment_service.go`
- [Search](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/search_service.go): service · Keyword search across knowledge content and supporting views. · `internal/service/search_service.go`
- [Users](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/service/user_service.go): service · User management and account-related orchestration. · `internal/service/user_service.go`
- [Domain models](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/domain/models.go): entities · Shared knowledge-wiki entities and metadata structures. · `internal/domain/models.go`

### Data layer

Repositories, database access, migrations, and file storage.

- [Database](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/db/db.go): Postgres access · Connection lifecycle and migration bootstrap support. · `internal/db/db.go`
- [Repositories](https://github.com/artjansentec/atlasknowledgeapi/tree/main/internal/repository): data access · Postgres query layer for users, projects, sections, lessons, files, tags, audits, and search helpers. · `internal/repository`
- [File storage](https://github.com/artjansentec/atlasknowledgeapi/blob/main/internal/storage/file_storage.go): filesystem store · Local filesystem persistence for uploaded files. · `internal/storage/file_storage.go`

### Shared packages

Cross-cutting helpers for validation and HTTP errors.

- [Validator](https://github.com/artjansentec/atlasknowledgeapi/blob/main/pkg/validator/validator.go): input validation · Central request validation utilities. · `pkg/validator/validator.go`
- [HTTP errors](https://github.com/artjansentec/atlasknowledgeapi/blob/main/pkg/httperr/errors.go): error mapping · Standardized API error representation and handling. · `pkg/httperr/errors.go`

## Connections

- API server → Handlers: serves · HTTP server wires routes and handlers.
- API server → Auth middleware: uses · Protects API routes with JWT and context middleware.
- API server → Database: connects · Initializes database access for requests.
- API server → OpenAPI docs: publishes · Serves the API contract and Swagger UI.
- Migrate → Database: migrates · Runs schema migration workflow.
- Create admin → Users: bootstraps · Creates the initial admin account.
- Handlers → Auth: calls · Auth endpoints delegate to business logic.
- Handlers → Projects: calls · Project endpoints delegate to business logic.
- Handlers → Sections: calls · Section endpoints delegate to business logic.
- Handlers → Lessons: calls · Lesson endpoints delegate to business logic.
- Handlers → Attachments: calls · Attachment endpoints delegate to business logic.
- Handlers → Search: calls · Search endpoints delegate to business logic.
- Handlers → Users: calls · User-related endpoints delegate to business logic.
- Handlers → Validator: validates · Request payload validation occurs at the boundary.
- Handlers → HTTP errors: formats · Handlers normalize failures into API errors.
- Handlers → Mappers: maps · Transforms domain data into response DTOs.
- Auth → Repositories: reads/writes · Uses user and session persistence for auth flows.
- Projects → Repositories: reads/writes · Persists projects and permission-related data.
- Sections → Repositories: reads/writes · Persists section hierarchy and ordering.
- Lessons → Repositories: reads/writes · Persists lesson content and relationships.
- Attachments → Repositories: reads/writes · Stores attachment metadata.
- Attachments → File storage: stores files · Writes and deletes physical upload content.
- Search → Repositories: queries · Builds search results from database queries.
- Users → Repositories: reads/writes · Manages user records and bootstrap/admin flows.
- Repositories → Database: uses · Repository queries run over the shared database connection.
- Repositories → Domain models: maps · Data access operates on shared entities.
- Mappers → Domain models: maps · Response mapping is based on domain entities.
- Auth → Domain models: uses · Auth logic works with core user and token-related entities.
- Projects → Domain models: uses · Project orchestration centers on domain entities.
- Sections → Domain models: uses · Section logic is built around shared entities.
- Lessons → Domain models: uses · Lesson logic is built around shared entities.
- Attachments → Domain models: uses · Attachment metadata and links use shared entities.
- Search → Domain models: uses · Search results are derived from shared entities and metadata.
