# sh0o0/otomo architecture

> Architecture diagram of the GitHub repository sh0o0/otomo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sh0o0/otomo
- Repository: https://github.com/sh0o0/otomo

## Overview

##### Main components
- API Backend – Look at the “api” directory that is written in Go. It is structured with controllers, services, and gRPC generation from Protobuf definitions. The backend includes its own test suites and internal packages for middleware, error handling, logging, and repository interactions.
- Frontend Client – The “frontend” directory shows a Flutter project structure (with Android, iOS, web, and Flutter-specific configurations). It manages UI views, controllers, view models, domain entities, and integrates with the API through generated gRPC stubs.
- Firebase Functions – Housed under the “firebase” directory. This part contains functions written in TypeScript (under firebase/functions), which likely provide additional services (possibly for authentication, real-time updates, notifications, or other integrations) and are configured with environment variables.
- gRPC/Proto Definitions – In the “grpc” folder, the proto files define the communication schema (for chat, date, health, location, and messaging) used to generate the necessary stubs for both client and server, making them a core part of the communication between the frontend and backend.
- Infrastructure – The “terraform” directory indicates that the deployment is managed via Terraform modules (for Cloud Run, load balancing, Google container registry, etc.). This part represents the cloud infrastructure where the API and possibly other microservices are deployed.
- CI/CD Pipelines – The “.github” directory hosts GitHub Actions workflows and custom actions (for API, Firebase, and Frontend) that automate testing, building, and deployment.
- Data Analytics – The “analysis” directory with BigQuery scripts shows that there’s an analytics component for managing data views, schema generation, or insights that may be used for monitoring or analysis of user interactions.

##### Relationships and interactions
- The Frontend (mobile/web clients) communicates with the API Backend via gRPC (or possibly REST endpoints generated from the protobuf definitions). The frontend is built in Flutter and interacts with the backend’s controllers/services.
- The API backend might also interact with external services (e.g., a messaging Pub/Sub service, geocoding services, or other microservices), as indicated in the internal service implementations and controller patterns.
- Firebase functions are designed to complement the backend by handling specific tasks (authentication, push notifications, or real-time chat support) and can communicate with both the backend and external services.
- Terraform-deployed infrastructure orchestrates and manages the deployment of these components (API deployed via Cloud Run, container registries, load balancers, etc.).
- CI/CD pipelines trigger builds and tests for these components and deploy them to the appropriate environments (as seen from the GitHub workflows and Terraform environments).
- The analysis scripts (BigQuery) interact with the data produced by these components, ensuring that usage data and logs are collected and available for analysis.

##### Architectural patterns and design principles
- Separation of concerns: The project is divided into distinct layers (frontend, backend, and infrastructure) with each having its own responsibilities.
- Microservices and serverless elements: The API (running on Cloud Run and written in Go) and Firebase functions represent independent units that can scale separately.
- gRPC communication: A clear pattern of using Protocol Buffers to define and facilitate structured communication between the client and server layers.
- CI/CD and Infrastructure as Code: The usage of GitHub Actions and Terraform suggests a DevOps-friendly design with automated deployments and environment consistency.

##### Elements
- Frontend Client (Flutter mobile/web)
- API Backend (Go, with internal layers like controllers, services, repositories, middleware)
- Firebase Functions (depicted as serverless functions)
- gRPC Services (or a shared communication layer between Frontend and API)
- Data Analytics (BigQuery and analysis scripts)
- Infrastructure layer (Terraform modules deploying Cloud Run, Load Balancer, etc.)
- CI/CD Pipelines (GitHub Actions workflows)
- From Frontend to API (gRPC calls/API requests)
- API interactions with external services and Firebase
- Data flow from API/Firebase to BigQuery for analytics
- CI/CD pipelines triggering deployments to the infrastructure layer
- Differentiate user-facing components (Frontend) from backend services (API, Firebase) and infrastructure components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
      FE["Frontend Client (Flutter)"]:::frontend
    end

    subgraph "Communication Layer"
      GRPC["gRPC/Proto Definitions"]:::proto
    end

    subgraph "Backend Layer"
      API["API Backend (Go)"]:::backend
      subgraph "API Internals"
        CONT["Controllers"]:::internal
        SERV["Services"]:::internal
        REPO["Repositories"]:::internal
        MID["Middleware & Logging"]:::internal
        CONT --> SERV
        SERV --> REPO
        REPO --> MID
      end
    end

    subgraph "Serverless Functions"
      FBF["Firebase Functions (TS)"]:::functions
    end

    subgraph "Analytics"
      ANALYTICS["Data Analytics (BigQuery)"]:::analytics
    end

    subgraph "Deployment & CI/CD"
      CICD["CI/CD Pipelines (GitHub Actions)"]:::cicd
      INFRA["Infrastructure (Terraform)"]:::infra
    end

    FE -->|"grpc_calls"| GRPC
    GRPC -->|"stub_calls"| API
    API -->|"invokes"| FBF
    API -->|"sends_logs"| ANALYTICS
    FBF -->|"pushes_data"| ANALYTICS
    CICD -->|"deploys_to"| INFRA
    INFRA -->|"hosts_API"| API
    INFRA -->|"hosts_FBF"| FBF
    INFRA -->|"deploys_FE"| FE
    CICD -->|"deploys_FE"| FE
    CICD -->|"deploys_API"| API
    CICD -->|"deploys_FBF"| FBF

    click FE "https://github.com/sh0o0/otomo/tree/develop/frontend/"
    click API "https://github.com/sh0o0/otomo/tree/develop/api/"
    click FBF "https://github.com/sh0o0/otomo/tree/develop/firebase/functions/"
    click GRPC "https://github.com/sh0o0/otomo/tree/develop/grpc/protos/"
    click INFRA "https://github.com/sh0o0/otomo/tree/develop/terraform/"
    click CICD "https://github.com/sh0o0/otomo/tree/develop/.github/"
    click ANALYTICS "https://github.com/sh0o0/otomo/tree/develop/analysis/"

classDef frontend fill:#dcedc1,stroke:#4caf50,stroke-width:2px;
classDef backend fill:#ffccbc,stroke:#f57c00,stroke-width:2px;
classDef functions fill:#ffe082,stroke:#ffb300,stroke-width:2px;
classDef proto fill:#bbdefb,stroke:#1976d2,stroke-width:2px;
classDef infra fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
classDef cicd fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
classDef analytics fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
classDef internal fill:#ef9a9a,stroke:#e53935,stroke-width:1px;
```
