::: {#header}

Architektur-Dokumentation: Trailmarks.io

::: {#toc .toc2} ::: {#toctitle} Table of Contents :::

1. Einführung und Ziele
2. Randbedingungen
- 2.1. Technische Randbedingungen
- 2.2. Organisatorische Randbedingungen
3. Kontextabgrenzung
- 3.1. Fachlicher Kontext
- 3.2. Technischer Kontext
4. Lösungsstrategie
- 4.1. Technologie-Entscheidungen
5. Bausteinsicht
- 5.1. Ebene 1: System-Container
- 5.2. Ebene 2: API Application Details
6. Laufzeitsicht
- 6.1. Trail Creation Szenario
7. Verteilungssicht
- 7.1. Deployment Struktur
8. Querschnittliche Konzepte
- 8.1. Logging und Monitoring
- 8.2. Sicherheit
9. Architekturentscheidungen
- 9.1. ADR-001: Verwendung von PostgreSQL
10. Risiken und technische Schulden
11. Glossar ::: :::

::: {#content} ::: sect1

{.anchor}1. Einführung und Ziele{.link}

::: sectionbody ::: sect2

{.anchor}1.1. Aufgabenstellung{.link}

::: paragraph Trailmarks.io ist eine moderne Webanwendung zum Tracking und Management von Trails (Wanderwege, Fahrradrouten, etc.). Die Anwendung ermöglicht es Nutzern, ihre Routen zu planen, zu verfolgen und mit anderen zu teilen. ::: :::

::: sect2

{.anchor}1.2. Qualitätsziele{.link}

::: sect2

{.anchor}1.3. Stakeholder{.link}

::: sect1

{.anchor}2. Randbedingungen{.link}

::: sectionbody ::: sect2

{.anchor}2.1. Technische Randbedingungen{.link}

::: ulist

Frontend: React/TypeScript
Backend: Node.js/TypeScript
Datenbank: PostgreSQL
Cloud: AWS/Azure
CI/CD: GitHub Actions ::: :::

::: sect2

{.anchor}2.2. Organisatorische Randbedingungen{.link}

::: ulist

Agile Entwicklung mit Scrum
Code Reviews erforderlich
Automatisierte Tests (>80% Coverage) ::: ::: ::: :::

::: sect1

{.anchor}3. Kontextabgrenzung{.link}

::: sectionbody ::: sect2

{.anchor}3.1. Fachlicher Kontext{.link}

::: listingblock ::: content Failed to generate image: undefined method `to_sym’ for nil:NilClass @startuml !include <C4/C4_Context>

Person(user, "Trail User", "Nutzer der Trailmarks.io Anwendung")
System(trailmarks, "Trailmarks.io", "Trail Tracking und Management System")
System_Ext(maps, "Maps Service", "Kartendienst (z.B. OpenStreetMap)")
System_Ext(weather, "Weather Service", "Wetterdienst")
System_Ext(social, "Social Media", "Social Media Integration")

Rel(user, trailmarks, "Nutzt", "HTTPS")
Rel(trailmarks, maps, "Holt Kartendaten", "HTTPS/API")
Rel(trailmarks, weather, "Holt Wetterdaten", "HTTPS/API")
Rel(trailmarks, social, "Teilt Inhalte", "HTTPS/API")

SHOW_LEGEND()
@enduml ::: ::: :::

::: sect2

{.anchor}3.2. Technischer Kontext{.link}

::: listingblock ::: content Failed to generate image: undefined method `to_sym’ for nil:NilClass @startuml !include <C4/C4_Context>

Person(user, "User", "Web Browser")
System(webapp, "Trailmarks.io WebApp", "React Frontend")
System(api, "Trailmarks.io API", "Node.js Backend")
SystemDb(db, "Database", "PostgreSQL")
System_Ext(cdn, "CDN", "Content Delivery Network")
System_Ext(auth, "Auth Service", "Authentication Provider")

Rel(user, webapp, "HTTPS")
Rel(webapp, api, "HTTPS/REST")
Rel(api, db, "SQL")
Rel(webapp, cdn, "HTTPS")
Rel(api, auth, "HTTPS/OAuth")

SHOW_LEGEND()
@enduml ::: ::: ::: ::: :::

::: sect1

{.anchor}4. Lösungsstrategie{.link}

::: sectionbody ::: sect2

{.anchor}4.1. Technologie-Entscheidungen{.link}

::: sect1

{.anchor}5. Bausteinsicht{.link}

::: sectionbody ::: sect2

{.anchor}5.1. Ebene 1: System-Container{.link}

::: listingblock ::: content Failed to generate image: undefined method `to_sym’ for nil:NilClass @startuml !include <C4/C4_Container>

Person(user, "Trail User")

System_Boundary(trailmarks, "Trailmarks.io") {
    Container(spa, "Single Page App", "React/TypeScript", "Stellt die Benutzeroberfläche bereit")
    Container(api, "API Application", "Node.js/Express", "Stellt REST API bereit")
    ContainerDb(db, "Database", "PostgreSQL", "Speichert Nutzerdaten, Trails, etc.")
}

System_Ext(maps, "Maps Service")
System_Ext(auth, "Auth Service")

Rel(user, spa, "Nutzt", "HTTPS")
Rel(spa, api, "API Calls", "HTTPS/JSON")
Rel(api, db, "Liest/Schreibt", "SQL")
Rel(api, maps, "Holt Karten", "HTTPS")
Rel(api, auth, "Authentifiziert", "HTTPS/OAuth")

SHOW_LEGEND()
@enduml ::: ::: :::

::: sect2

{.anchor}5.2. Ebene 2: API Application Details{.link}

::: listingblock ::: content Failed to generate image: undefined method `to_sym’ for nil:NilClass @startuml !include <C4/C4_Component>

Container_Boundary(api, "API Application") {
    Component(controller, "REST Controllers", "Express", "Behandelt HTTP Requests")
    Component(service, "Business Logic", "TypeScript", "Implementiert Geschäftslogik")
    Component(repository, "Data Access", "TypeScript", "Datenzugriff")
    Component(auth, "Auth Module", "TypeScript", "Authentifizierung und Autorisierung")
}

ContainerDb(db, "Database")
System_Ext(extAuth, "External Auth")

Rel(controller, service, "Nutzt")
Rel(service, repository, "Nutzt")
Rel(repository, db, "SQL")
Rel(controller, auth, "Validiert")
Rel(auth, extAuth, "OAuth")

SHOW_LEGEND()
@enduml ::: ::: ::: ::: :::

::: sect1

{.anchor}6. Laufzeitsicht{.link}

::: sectionbody ::: sect2

{.anchor}6.1. Trail Creation Szenario{.link}

::: listingblock ::: content Failed to generate image: undefined method `to_sym’ for nil:NilClass @startuml actor User participant “React App” as UI participant “API Gateway” as API participant “Trail Service” as Service participant “Database” as DB

User -> UI: Create new trail
UI -> API: POST /api/trails
API -> Service: createTrail(data)
Service -> DB: INSERT trail
DB --> Service: trail_id
Service --> API: Trail created
API --> UI: 201 Created
UI --> User: Success message
@enduml ::: ::: ::: ::: :::

::: sect1

{.anchor}7. Verteilungssicht{.link}

::: sectionbody ::: sect2

{.anchor}7.1. Deployment Struktur{.link}

::: listingblock ::: content Failed to generate image: undefined method `to_sym’ for nil:NilClass @startuml !include <C4/C4_Deployment>

Deployment_Node(aws, "Amazon Web Services", "Cloud Provider") {
    Deployment_Node(cdn, "CloudFront", "CDN") {
        Container(static, "Static Files", "HTML/CSS/JS")
    }

    Deployment_Node(ecs, "ECS Cluster", "Container Orchestration") {
        Container(api1, "API Instance 1", "Node.js")
        Container(api2, "API Instance 2", "Node.js")
    }

    Deployment_Node(rds, "RDS", "Managed Database") {
        ContainerDb(db, "PostgreSQL Database")
    }
}

Rel(static, api1, "API Calls")
Rel(api1, db, "SQL")
Rel(api2, db, "SQL")

SHOW_LEGEND()
@enduml ::: ::: ::: ::: :::

::: sect1