::: {#header}

Architecture Documentation: Trailmarks.io

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

1. Introduction and Goals
2. Architecture Constraints
- 2.1. Technical Constraints
- 2.2. Organizational Constraints
3. Context and Scope
- 3.1. Business Context
- 3.2. Technical Context
4. Solution Strategy
- 4.1. Technology Decisions
5. Building Block View
- 5.1. Level 1: System Containers
- 5.2. Level 2: API Application Details
6. Runtime View
- 6.1. Trail Creation Scenario
7. Deployment View
- 7.1. Deployment Structure
8. Cross-cutting Concepts
- 8.1. Logging and Monitoring
- 8.2. Security
9. Architecture Decisions
- 9.1. ADR-001: Use of PostgreSQL
10. Risks and Technical Debt
11. Glossary ::: :::

::: {#content} ::: sect1

{.anchor}1. Introduction and Goals{.link}

::: sectionbody ::: sect2

{.anchor}1.1. Requirements Overview{.link}

::: paragraph Trailmarks.io is a modern web application for tracking and managing trails (hiking trails, bike routes, etc.). The application enables users to plan, track, and share their routes with others. ::: :::

::: sect2

{.anchor}1.2. Quality Goals{.link}

::: sect2

{.anchor}1.3. Stakeholders{.link}

::: sect1

{.anchor}2. Architecture Constraints{.link}

::: sectionbody ::: sect2

{.anchor}2.1. Technical Constraints{.link}

::: ulist

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

::: sect2

{.anchor}2.2. Organizational Constraints{.link}

::: ulist

Agile development with Scrum
Code reviews required
Automated tests (>80% coverage) ::: ::: ::: :::

::: sect1

{.anchor}3. Context and Scope{.link}

::: sectionbody ::: sect2

{.anchor}3.1. Business Context{.link}

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

Person(user, "Trail User", "User of the Trailmarks.io application")
System(trailmarks, "Trailmarks.io", "Trail tracking and management system")
System_Ext(maps, "Maps Service", "Map service (e.g., OpenStreetMap)")
System_Ext(weather, "Weather Service", "Weather service")
System_Ext(social, "Social Media", "Social media integration")

Rel(user, trailmarks, "Uses", "HTTPS")
Rel(trailmarks, maps, "Fetches map data", "HTTPS/API")
Rel(trailmarks, weather, "Fetches weather data", "HTTPS/API")
Rel(trailmarks, social, "Shares content", "HTTPS/API")

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

::: sect2

{.anchor}3.2. Technical Context{.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. Solution Strategy{.link}

::: sectionbody ::: sect2

{.anchor}4.1. Technology Decisions{.link}

::: sect1

{.anchor}5. Building Block View{.link}

::: sectionbody ::: sect2

{.anchor}5.1. Level 1: System Containers{.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", "Provides the user interface")
    Container(api, "API Application", "Node.js/Express", "Provides REST API")
    ContainerDb(db, "Database", "PostgreSQL", "Stores user data, trails, etc.")
}

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

Rel(user, spa, "Uses", "HTTPS")
Rel(spa, api, "API Calls", "HTTPS/JSON")
Rel(api, db, "Reads/Writes", "SQL")
Rel(api, maps, "Fetches maps", "HTTPS")
Rel(api, auth, "Authenticates", "HTTPS/OAuth")

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

::: sect2

{.anchor}5.2. Level 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", "Handles HTTP requests")
    Component(service, "Business Logic", "TypeScript", "Implements business logic")
    Component(repository, "Data Access", "TypeScript", "Data access layer")
    Component(auth, "Auth Module", "TypeScript", "Authentication and authorization")
}

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

Rel(controller, service, "Uses")
Rel(service, repository, "Uses")
Rel(repository, db, "SQL")
Rel(controller, auth, "Validates")
Rel(auth, extAuth, "OAuth")

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

::: sect1

{.anchor}6. Runtime View{.link}

::: sectionbody ::: sect2

{.anchor}6.1. Trail Creation Scenario{.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. Deployment View{.link}

::: sectionbody ::: sect2

{.anchor}7.1. Deployment Structure{.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