BaSyx Go Components

Welcome to the BaSyx Go project! This guide is designed to help new developers onboard quickly, understand the architecture, and contribute effectively.

Table of Contents

1. Project Overview
2. Architecture Overview
3. Setup & Installation
4. Environment Variables & Configuration
5. Code Style & Conventions
6. Module Structure
7. Common Workflows
8. API Usage
9. Contribution Guidelines
10. Repository Automation
11. Troubleshooting & Error Reference
12. Glossary of Terms & Abbreviations

---

1. Project Overview

BaSyx Go Components is an open-source implementation of the Eclipse BaSyx framework in Go, providing Asset Administration Shell (AAS) API components like registries, repositories, and more. The project is modular, scalable, and designed for industrial digital twin scenarios.

2. Architecture Overview

The project is composed of microservices for AAS and Submodel registries, AAS and Submodel repositories, the AAS discovery service, and the AASX file server. Each service exposes REST APIs and interacts with a PostgreSQL database. Security is enforced via OIDC and ABAC middleware. See docu/security/REGISTRY_SECURITY.md for a detailed flow and architecture diagram.

3. Setup & Installation

Prerequisites

• Go >= 1.20
• Docker & Docker Compose
• PostgreSQL (for local development)

Steps

1. Clone the repository:

   git clone https://github.com/eclipse-basyx/basyx-go-components.git
   cd basyx-go-components

2. Install dependencies:

   go mod tidy

3. Start services (example):

   go run ./cmd/submodelrepositoryservice/main.go -config ./cmd/submodelrepositoryservice/config.yaml -databaseSchema ./basyxschema.sql

4. Run integration tests:

   go test -v ./internal/submodelrepository/integration_tests

5. Use Docker Compose for multi-service setup:

   docker-compose -f examples/BaSyxMinimalExample/docker-compose.yml up

4. Environment Variables & Configuration

Configuration is managed via YAML files in cmd/<service>/config.yaml and environment variables. Key variables include database connection settings (see docu/errors.md for troubleshooting):

maxOpenConnections: 500
maxIdleConnections: 500
connMaxLifetimeMinutes: 5

Or via .env:

POSTGRES_MAXOPENCONNECTIONS=500
POSTGRES_MAXIDLECONNECTIONS=500
POSTGRES_CONNMAXLIFETIMEMINUTES=5

5. Code Style & Conventions

• Use Go modules (go.mod) for dependency management
• Follow GoDoc conventions (godoc_tips.md)
• Run the linter before submitting PRs:

  ./lint.sh

• Use //nolint:<linter> comments sparingly and explain why
• Auto-generated model files may not conform to all linter rules

6. Module Structure

• cmd/ - Service entry points, configs, Dockerfiles
• api/ - OpenAPI specs and API layer
• internal/ - Core business logic, persistence, integration tests
• pkg/ - Autogenerated API Files
• examples/ - Minimal working examples, Docker Compose setups
• docu/ - Documentation, error explanations, security notes
• basyx-database-wiki/ - Database schema documentation

See structure.md and related files for details on each module.

7. Common Workflows

Build & Run

• Build and run services:

  go run ./cmd/<service>/main.go -config ./cmd/<service>/config.yaml

• Use VSCode launch scripts in .vscode/launch.json for debugging

Test

• Run all tests:

  go test -v ./internal/...

• Run integration tests for a component:

  go test -v ./internal/<component>/integration_tests

Lint

• Run linter:

  ./lint.sh

8. API Usage

• OpenAPI specs are in api/<service>/openapi.yaml
• Use generated API clients in pkg/
• Example endpoint: /submodels/{id}/submodel-elements/{idShort}/attachment
• See structure_api.md for details

9. Contribution Guidelines

• Fork the repository and create a feature branch
• Write clear commit messages and PR descriptions
• Add/update GoDoc comments for all exported code
• Run tests and linter before submitting
• Cover new features with integration tests
• Document public APIs in OpenAPI YAML files

10. Repository Automation

• CI/CD pipelines run tests and linter on each PR
• Ensure your local environment matches CI versions (see linter.md)
• Use provided tasks in VSCode or CLI for build/test/lint automation

11. Troubleshooting & Error Reference

• See docu/errors.md for common error scenarios and solutions
• For security and authorization, see docu/security/REGISTRY_SECURITY.md

12. Glossary of Terms & Abbreviations

• AAS: Asset Administration Shell – digital representation of assets
• Submodel: Modular part of an AAS
• SME: Submodel Element
• OIDC: OpenID Connect – authentication protocol
• ABAC: Attribute-Based Access Control
• OpenAPI: Specification for RESTful APIs

---

For further details, see the docs folder, the basyx wiki and links above. If you encounter issues, please open an issue on GitHub or consult the error documentation.

Database Schema

See basyx-database-wiki and sql_examples for details on tables, relationships, and large object handling.

Frequently Asked Questions

Q: How do I add a new component?

• Add main.go in cmd/<COMPONENT_NAME>/main.go
• Implement the logic in internal/<COMPONENT_NAME>/
• Save and Use OpenAPI specs in api/<COMPONENT_NAME>/openapi.yaml
• Add tests in internal/<COMPONENT_NAME>/integration_tests/

Q: How do I handle file attachments?

• Use the File SME logic in internal/submodelrepository/persistence/Submodel/submodelElements/FileHandler.go
• See integration tests for upload/download examples

Q: Where do I find API documentation?

• OpenAPI YAML files in api/
• GoDoc for package-level documentation

Further Reading

• Eclipse BaSyx Documentation
• IDTA AAS Specification

---

For any questions, open an issue or contact the maintainers.