How artjansentec/atlasknowledgeapi works
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: handler Handlers · repository Repositories · models.go Domain models · main.go API server
Components 20
Entry points
Runnable processes for serving the API, running migrations, and bootstrapping admin access.
- API server · Starts the Echo HTTP API process.
cmd/api/main.go - Migrate · Applies database schema migrations.
cmd/migrate/main.go - Create admin · Bootstraps the first admin user.
cmd/create-admin/main.go
HTTP layer
Echo handlers, middleware, mappers, and API presentation assets.
- Handlers · Route handlers for auth, health, projects, sections, lessons, attachments, and search.
internal/handler - Auth middleware · JWT and request-context middleware for protected routes.
internal/middleware/auth.go - Mappers · Converts domain objects into API response shapes.
internal/mapper - OpenAPI docs · Swagger/OpenAPI definition and embedded docs assets.
internal/handler/openapi.yaml
Core domain
Business services and shared domain models.
- Auth · Login, refresh, logout, and current-user flow.
internal/service/auth_service.go - Projects · Project lifecycle, permissions, and hierarchy orchestration.
internal/service/project_service.go - Sections · Section CRUD and ordering within projects.
internal/service/section_service.go - Lessons · Lesson CRUD and content updates under sections.
internal/service/lesson_service.go - Attachments · Coordinates upload, download, metadata, and deletion.
internal/service/attachment_service.go - Search · Keyword search across knowledge content and supporting views.
internal/service/search_service.go - Users · User management and account-related orchestration.
internal/service/user_service.go - Domain models · Shared knowledge-wiki entities and metadata structures.
internal/domain/models.go
Data layer
Repositories, database access, migrations, and file storage.
- Database · Connection lifecycle and migration bootstrap support.
internal/db/db.go - Repositories · Postgres query layer for users, projects, sections, lessons, files, tags, audits, and search helpers.
internal/repository - File storage · Local filesystem persistence for uploaded files.
internal/storage/file_storage.go
Shared packages
Cross-cutting helpers for validation and HTTP errors.
- Validator · Central request validation utilities.
pkg/validator/validator.go - HTTP errors · Standardized API error representation and handling.
pkg/httperr/errors.go
Connections 33
- 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.