# kajilabteam/walking-information-storage-server architecture

> Architecture diagram of the GitHub repository kajilabteam/walking-information-storage-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kajilabteam/walking-information-storage-server
- Repository: https://github.com/kajilabteam/walking-information-storage-server

## Overview

##### Project Type and Purpose
- This is a backend service for accumulating walking data and estimating current position information.
- The project follows a layered or Clean Architecture style with clear divisions between presentation, application, domain, and infrastructure layers.

##### Main Components from the File Structure
- Docker Configuration:
- docker/postgres: Contains Dockerfile and SQL migration/demo scripts to set up the Postgres database container.
- docker/server: Contains the Dockerfile for running the application server container.
- Server Directory (backend application):
- Presentation Layer: Under server/presentation/handlers. This layer exposes REST API endpoints (e.g., health_check_handler, start_walking_handler) that handle incoming HTTP requests.
- Application Layer: Under server/application where DTOs, services (health_check_service, move_pedestrian_service, etc.), and error handling logic reside.
- Domain Layer: Located in server/domain. Contains the business logic with models (for particles, floor_maps, walking parameters) and domain-specific errors. This layer encapsulates the core domain knowledge.
- Infrastructure Layer: In server/infrastructure. This handles lower-level concerns like database connections, repository implementations, and integration with external file services.
- Configuration & Utility Files:
- Files such as .env.example, configuration files in server/config, and utility modules under server/utils are used to manage environment settings and helper methods.
- Development and Deployment Tools:
- Makefile for command-line tasks, pre-commit configuration, and various Docker-related scripts.

##### Relationships and Data Flow
- Client requests hit the Presentation Layer (handlers) which then delegate to the Application Layer’s services.
- The Application Services encapsulate use-case logic (e.g., starting or finishing a walking session, moving a pedestrian) and interact with the Domain Layer where core business models and logic are enforced.
- Persistence and Repository patterns are used to abstract data access. The Infrastructure Layer (with specific repository implementations) communicates with the Postgres database container that is set up by the Docker Compose configuration.
- The application’s error handling flows from the Domain and Application layers up to the Presentation layer to provide appropriate responses.

##### Architectural Patterns and Important Technologies
- Layered (or Clean) Architecture: Separates concerns across presentation, application, domain, and infrastructure layers.
- Docker Containerization: The project uses separate containers for the server, Postgres database, and Schemaspy. Docker Compose orchestrates these containers.
- REST API: Exposed via uvicorn and FastAPI (implied by uvicorn invocation and standard Python practices).
- Database Migrations: SQL migration files in the docker/postgres directory indicate a structured approach to managing database schema evolution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::client

    %% Docker Configuration Section
    subgraph "Docker Configuration"
        compose1["Compose File: docker-compose.yml"]:::docker
        compose2["Compose File: docker-compose-spy.yml"]:::docker
        postgres["Postgres Container"]:::docker
        schemaspy["Schemaspy Container"]:::docker
        serverContainer["Server Container"]:::docker
    end

    %% Backend Application inside Server Container
    subgraph "Backend Application (Inside Server Container)"
        direction TB
        pres["Presentation Layer (Handlers)"]:::layer
        app["Application Layer (Services, DTOs, Error Handling)"]:::layer
        dom["Domain Layer (Business Logic & Models)"]:::layer
        infra["Infrastructure Layer (Repositories & External Services)"]:::layer
    end

    %% Configuration & Utility Files
    configUtil["Configuration & Utility Files"]:::config

    %% Database
    db["Postgres Database"]:::database

    %% Data Flow
    Client -->|"sends API request"| pres
    pres -->|"calls"| app
    app -->|"invokes"| dom
    dom -->|"persists via"| infra
    infra -->|"queries/inserts into"| db

    %% Docker Infrastructure Relationships
    serverContainer --- pres
    serverContainer --- app
    serverContainer --- dom
    serverContainer --- infra
    compose1 --- serverContainer
    compose2 --- schemaspy
    compose1 --- postgres
    compose2 --- postgres

    %% Configuration usage
    configUtil --- serverContainer

    %% Click Events
    click compose1 "https://github.com/kajilabteam/walking-information-storage-server/blob/dev/docker-compose.yml"
    click compose2 "https://github.com/kajilabteam/walking-information-storage-server/blob/dev/docker-compose-spy.yml"
    click postgres "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/docker/postgres"
    click schemaspy "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/docker/schemaspy"
    click serverContainer "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/docker/server/Dockerfile"
    click pres "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/presentation/handlers"
    click app "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/application/services"
    click app "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/application/dto"
    click app "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/application/errors"
    click dom "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/domain"
    click dom "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/domain/repository_impl"
    click infra "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/infrastructure"
    click infra "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/infrastructure/persistence/repository"
    click infra "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/infrastructure/external/services"
    click configUtil "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/config"
    click configUtil "https://github.com/kajilabteam/walking-information-storage-server/tree/dev/server/utils"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef docker fill:#cde,stroke:#036,stroke-width:2px,stroke-dasharray: 5 5;
    classDef layer fill:#ffd,stroke:#bb8800,stroke-width:2px;
    classDef database fill:#afa,stroke:#080,stroke-width:2px;
    classDef config fill:#eef,stroke:#667,stroke-width:2px;
```
