Trailmarks - Hiking Stones Overview

A modern web application for displaying and managing hiking stones (Wandersteine).

🚀 Quick Start

With Docker (Recommended)

git clone https://github.com/trailmarks-io/trailmarks.git
cd trailmarks
docker-compose up -d

Access the application:

• 🌐 Frontend: http://localhost:4200
• 🔌 Backend API: http://localhost:8080
• 📚 API Documentation: http://localhost:8080/swagger
• 🔐 Keycloak Admin: http://localhost:8180
• 📊 Tracing UI: http://localhost:16686

Local Development

Backend:

cd backend
dotnet run

Frontend:

cd frontend
npm install
npx ng serve

✨ Features

✅ REST API with C# ASP.NET Core 10.0
✅ PostgreSQL database with Entity Framework Core
✅ Angular 20.1.0 frontend with Tailwind CSS
✅ Multi-language support (German/English)
✅ Keycloak authentication and authorization
✅ Docker deployment with Docker Compose
✅ OpenTelemetry instrumentation with Jaeger tracing
✅ Responsive design for mobile devices
✅ Comprehensive testing (xUnit, Jasmine/Karma, Playwright)

📚 Documentation

Comprehensive documentation is available in the docs/ folder:

• Architecture Documentation - Technical architecture following ARC42 template
• User Guide - End user documentation
• Admin Guide - System administration and content management

Note: The documentation is written in AsciiDoc format and can be converted to HTML/Markdown for viewing.

🛠️ Technology Stack

• Backend: .NET 10.0, ASP.NET Core, Entity Framework Core
• Frontend: Angular 20.1.0, TypeScript, Tailwind CSS
• Database: PostgreSQL 16 with PostGIS
• Authentication: Keycloak 26.0.7 (OpenID Connect / OAuth2)
• API Documentation: OpenAPI 3.0 / Swagger
• Observability: OpenTelemetry, Jaeger
• Containerization: Docker, Docker Compose

📁 Project Structure

trailmarks/
├── backend/              # .NET 10.0 Backend API
│   ├── src/             # Application source code
│   └── test/            # xUnit tests
├── frontend/            # Angular 20.1 Frontend
│   ├── src/             # Application source code
│   ├── e2e/             # Playwright E2E tests
│   └── public/          # Static assets
├── docs/                # Documentation (AsciiDoc)
│   ├── architecture/    # ARC42 architecture docs
│   ├── user-guide/      # End user guide
│   └── admin-guide/     # Admin & moderator guide
└── docker-compose.yml   # Docker deployment

🧪 Testing

# Backend tests
cd backend && dotnet test

# Frontend unit tests
cd frontend && npx ng test

# Frontend E2E tests
cd frontend && npm run e2e

🔨 Building

# Backend
cd backend && dotnet build

# Frontend
cd frontend && npx ng build

🤝 Contributing

Contributions are welcome! Please see the architecture documentation for technical details.

Git Workflow

• Main branch: main - stable production code
• Development branch: develop - active development
• Feature branches: <issue-number>-description
• Commit convention: Conventional Commits

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• Documentation: Full Documentation
• Issues: https://github.com/trailmarks-io/trailmarks/issues
• API Documentation: http://localhost:8080/swagger