# fmoorenoo/haircloud architecture

> Architecture diagram of the GitHub repository fmoorenoo/haircloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fmoorenoo/haircloud
- Repository: https://github.com/fmoorenoo/haircloud

## Overview

HairCloud is an Android app backed by a Flask REST API and PostgreSQL. Clients authenticate, discover shops and services, book and review appointments; professionals manage shop details, services, staff, schedules, appointments and reports. The Android path runs from navigation/screens through ViewModels and repositories to Retrofit; the backend applies domain rules and persists data. The README documents capabilities not visible in sampled excerpts, so those subsystems are represented without asserting unverified internal calls.

Main entry points: [`backend/app/api`](https://github.com/fmoorenoo/haircloud/tree/main/backend/app/api) (Flask API), [`backend/app/db.py`](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/db.py) (PostgreSQL), [`backend/app/api/auth.py`](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/auth.py) (Authentication endpoints), [`backend/app/services/appointments.py`](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/appointments.py) (Appointment rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Android app"]
  node_android["Android entry<br/>[MainActivity.kt]"]
  node_navigation["App navigation<br/>[AppNavigation.kt]"]
  node_client_screens["Client screens"]
  node_pro_screens["Professional screens"]
  node_viewmodels["ViewModels"]
  node_repositories["Repositories"]
  node_api_client["API client<br/>[ApiClient.kt]"]
  node_api_service["API service<br/>[ApiService.kt]"]
  node_session["Session manager<br/>[SessionManager.kt]"]
  node_token_store["Encrypted token store<br/>[TokenManager.kt]"]
end

subgraph group_backend["REST API"]
  node_flask_api["Flask API"]
  node_auth_api["Authentication endpoints<br/>[auth.py]"]
  node_appointment_api["Appointment endpoints<br/>[appointments.py]"]
  node_catalog_api["Shop and catalog endpoints"]
  node_review_api["Review endpoints<br/>[reviews.py]"]
  node_validation["Request validation<br/>[schemas.py]"]
  node_serializers["Resource serialization<br/>[serializers.py]"]
end

subgraph group_domain["Business services"]
  node_appointment_rules["Appointment rules<br/>[appointments.py]"]
  node_availability["Availability rules<br/>[availability.py]"]
  node_statistics["Reports and statistics<br/>[stats.py]"]
  node_verification["Email verification<br/>[verification.py]"]
end

subgraph group_security["Identity and security"]
  node_authz["Authentication and roles<br/>[auth.py]"]
  node_tokens["Access and refresh tokens<br/>[tokens.py]"]
  node_audit["Security audit<br/>[audit.py]"]
end

subgraph group_persistence["Persistence and delivery"]
  node_database[("PostgreSQL<br/>[db.py]")]
  node_mailer["Email delivery<br/>[mailer.py]"]
  node_errors["API error handling<br/>[errors.py]"]
end

node_clients(("Clients"))
node_professionals(("Shop professionals"))

node_clients -->|"uses"| node_android
node_professionals -->|"uses"| node_android
node_android -->|"starts"| node_navigation
node_navigation -->|"routes to"| node_client_screens
node_navigation -->|"routes to"| node_pro_screens
node_client_screens -->|"uses"| node_viewmodels
node_pro_screens -->|"uses"| node_viewmodels
node_viewmodels -->|"delegates to"| node_repositories
node_repositories -->|"calls"| node_api_client
node_api_client -->|"creates"| node_api_service
node_api_client -->|"reads and refreshes"| node_session
node_session -->|"persists"| node_token_store
node_api_service -->|"sends REST requests"| node_flask_api
node_flask_api -.->|"routes authentication"| node_auth_api
node_flask_api -.->|"routes appointments"| node_appointment_api
node_flask_api -.->|"routes shop operations"| node_catalog_api
node_flask_api -.->|"routes reviews"| node_review_api
node_appointment_api -.->|"delegates to"| node_appointment_rules
node_appointment_rules -->|"checks availability"| node_availability
node_appointment_rules -->|"sends notices"| node_mailer
node_appointment_rules -->|"reads and writes"| node_database
node_auth_api -->|"authenticates requests"| node_authz
node_auth_api -->|"issues tokens"| node_tokens
node_auth_api -->|"delegates verification"| node_verification
node_verification -->|"sends email"| node_mailer
node_authz -->|"decodes tokens"| node_tokens
node_tokens -->|"records reuse"| node_audit
node_authz -->|"loads user"| node_database
node_review_api -->|"checks access"| node_authz
node_review_api -->|"queries reviews"| node_database
node_catalog_api -->|"validates input"| node_validation
node_catalog_api -->|"formats resource"| node_serializers
node_catalog_api -->|"queries catalog"| node_database
node_validation -->|"raises validation errors"| node_errors
node_statistics -.->|"reads metrics"| node_database

click node_android "https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/MainActivity.kt"
click node_navigation "https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/navigation/AppNavigation.kt"
click node_client_screens "https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/screens/client"
click node_pro_screens "https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/screens/barber"
click node_viewmodels "https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/viewmodel"
click node_repositories "https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/data/repository"
click node_api_client "https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/ApiClient.kt"
click node_api_service "https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/ApiService.kt"
click node_session "https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/SessionManager.kt"
click node_token_store "https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/storage/TokenManager.kt"
click node_flask_api "https://github.com/fmoorenoo/haircloud/tree/main/backend/app/api"
click node_auth_api "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/auth.py"
click node_appointment_api "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/appointments.py"
click node_catalog_api "https://github.com/fmoorenoo/haircloud/tree/main/backend/app/api"
click node_review_api "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/reviews.py"
click node_appointment_rules "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/appointments.py"
click node_availability "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/availability.py"
click node_statistics "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/stats.py"
click node_verification "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/verification.py"
click node_authz "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/security/auth.py"
click node_tokens "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/security/tokens.py"
click node_audit "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/security/audit.py"
click node_validation "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/schemas.py"
click node_serializers "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/serializers.py"
click node_database "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/db.py"
click node_mailer "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/mailer.py"
click node_errors "https://github.com/fmoorenoo/haircloud/blob/main/backend/app/errors.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android,node_navigation,node_client_screens,node_pro_screens,node_viewmodels,node_repositories,node_api_client,node_api_service,node_session,node_token_store,node_clients toneBlue
class node_flask_api,node_auth_api,node_appointment_api,node_catalog_api,node_review_api,node_validation,node_serializers toneAmber
class node_appointment_rules,node_availability,node_statistics,node_verification toneMint
class node_authz,node_tokens,node_audit toneRose
class node_database,node_mailer,node_errors,node_professionals toneIndigo
```

## Components

### Android app

- [Android entry](https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/MainActivity.kt): `frontend/app/src/main/java/com/haircloud/MainActivity.kt`
- [App navigation](https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/navigation/AppNavigation.kt): `frontend/app/src/main/java/com/haircloud/navigation/AppNavigation.kt`
- [Client screens](https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/screens/client): `frontend/app/src/main/java/com/haircloud/screens/client`
- [Professional screens](https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/screens/barber): `frontend/app/src/main/java/com/haircloud/screens/barber`
- [ViewModels](https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/viewmodel): `frontend/app/src/main/java/com/haircloud/viewmodel`
- [Repositories](https://github.com/fmoorenoo/haircloud/tree/main/frontend/app/src/main/java/com/haircloud/data/repository): `frontend/app/src/main/java/com/haircloud/data/repository`
- [API client](https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/ApiClient.kt): `frontend/app/src/main/java/com/haircloud/data/ApiClient.kt`
- [API service](https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/ApiService.kt): `frontend/app/src/main/java/com/haircloud/data/ApiService.kt`
- [Session manager](https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/SessionManager.kt): `frontend/app/src/main/java/com/haircloud/data/SessionManager.kt`
- [Encrypted token store](https://github.com/fmoorenoo/haircloud/blob/main/frontend/app/src/main/java/com/haircloud/data/storage/TokenManager.kt): `frontend/app/src/main/java/com/haircloud/data/storage/TokenManager.kt`

### REST API

- [Flask API](https://github.com/fmoorenoo/haircloud/tree/main/backend/app/api): `backend/app/api`
- [Authentication endpoints](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Appointment endpoints](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/appointments.py): `backend/app/api/appointments.py`
- [Shop and catalog endpoints](https://github.com/fmoorenoo/haircloud/tree/main/backend/app/api): `backend/app/api`
- [Review endpoints](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/api/reviews.py): `backend/app/api/reviews.py`
- [Request validation](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Resource serialization](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/serializers.py): `backend/app/serializers.py`

### Business services

- [Appointment rules](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/appointments.py): `backend/app/services/appointments.py`
- [Availability rules](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/availability.py): `backend/app/services/availability.py`
- [Reports and statistics](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/stats.py): `backend/app/services/stats.py`
- [Email verification](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/verification.py): `backend/app/services/verification.py`

### Identity and security

- [Authentication and roles](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/security/auth.py): `backend/app/security/auth.py`
- [Access and refresh tokens](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/security/tokens.py): `backend/app/security/tokens.py`
- [Security audit](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/security/audit.py): `backend/app/security/audit.py`

### Persistence and delivery

- [PostgreSQL](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/db.py): `backend/app/db.py`
- [Email delivery](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/services/mailer.py): `backend/app/services/mailer.py`
- [API error handling](https://github.com/fmoorenoo/haircloud/blob/main/backend/app/errors.py): `backend/app/errors.py`

### Other components

- **Clients**
- **Shop professionals**

## Connections

- Clients → Android entry: uses (evidence: `README.md`)
- Shop professionals → Android entry: uses (evidence: `README.md`)
- Android entry → App navigation: starts (evidence: `frontend/app/src/main/java/com/haircloud/MainActivity.kt`)
- App navigation → Client screens: routes to (evidence: `frontend/app/src/main/java/com/haircloud/navigation/AppNavigation.kt`)
- App navigation → Professional screens: routes to (evidence: `frontend/app/src/main/java/com/haircloud/navigation/AppNavigation.kt`)
- Client screens → ViewModels: uses (evidence: `frontend/app/src/main/java/com/haircloud/screens/client/ClientProfileScreen.kt`)
- Professional screens → ViewModels: uses (evidence: `frontend/app/src/main/java/com/haircloud/screens/barber/BarbershopServicesScreen.kt`)
- ViewModels → Repositories: delegates to (evidence: `frontend/app/src/main/java/com/haircloud/viewmodel/AuthViewModel.kt`)
- Repositories → API client: calls (evidence: `frontend/app/src/main/java/com/haircloud/data/repository/AuthRepository.kt`)
- API client → API service: creates (evidence: `frontend/app/src/main/java/com/haircloud/data/ApiClient.kt`)
- API client → Session manager: reads and refreshes (evidence: `frontend/app/src/main/java/com/haircloud/data/ApiClient.kt`)
- Session manager → Encrypted token store: persists (evidence: `frontend/app/src/main/java/com/haircloud/data/SessionManager.kt`)
- API service → Flask API: sends REST requests (evidence: `README.md`)
- Flask API → Authentication endpoints: routes authentication
- Flask API → Appointment endpoints: routes appointments
- Flask API → Shop and catalog endpoints: routes shop operations
- Flask API → Review endpoints: routes reviews
- Appointment endpoints → Appointment rules: delegates to
- Appointment rules → Availability rules: checks availability (evidence: `backend/app/services/appointments.py`)
- Appointment rules → Email delivery: sends notices (evidence: `backend/app/services/appointments.py`)
- Appointment rules → PostgreSQL: reads and writes (evidence: `backend/app/services/appointments.py`)
- Authentication endpoints → Authentication and roles: authenticates requests (evidence: `backend/app/api/auth.py`)
- Authentication endpoints → Access and refresh tokens: issues tokens (evidence: `backend/app/api/auth.py`)
- Authentication endpoints → Email verification: delegates verification (evidence: `backend/app/api/auth.py`)
- Email verification → Email delivery: sends email (evidence: `backend/app/services/verification.py`)
- Authentication and roles → Access and refresh tokens: decodes tokens (evidence: `backend/app/security/auth.py`)
- Access and refresh tokens → Security audit: records reuse (evidence: `backend/app/security/tokens.py`)
- Authentication and roles → PostgreSQL: loads user (evidence: `backend/app/security/auth.py`)
- Review endpoints → Authentication and roles: checks access (evidence: `backend/app/api/reviews.py`)
- Review endpoints → PostgreSQL: queries reviews (evidence: `backend/app/api/reviews.py`)
- Shop and catalog endpoints → Request validation: validates input (evidence: `backend/app/api/services.py`)
- Shop and catalog endpoints → Resource serialization: formats resource (evidence: `backend/app/api/services.py`)
- Shop and catalog endpoints → PostgreSQL: queries catalog (evidence: `backend/app/api/services.py`)
- Request validation → API error handling: raises validation errors (evidence: `backend/app/schemas.py`)
- Reports and statistics → PostgreSQL: reads metrics
