# tyball21/open-hams architecture

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

- Interactive diagram: https://gitdiagram.com/tyball21/open-hams
- Repository: https://github.com/tyball21/open-hams

## Overview

##### Main System Components

A. Frontend Layer (React/Vite Application)
- User Interface Components
- State Management
- API Integration Layer
- Authentication/Authorization

B. Backend Layer (FastAPI)
- API Routes
- Business Logic
- Authentication/Security
- Database Access Layer

C. Database Layer (MySQL)
- Data Storage
- Migrations (Alembic)

D. External Services
- Email Service (hams-mails)

##### Component Relationships and Details

Frontend Section:
- Dashboard Components
- Authentication Routes
- Event Management
- Animal Management
- User Management
- API Integration Layer
- UI Components Library

Backend Section:
- API Routes (/api/routes/)
- Core Services (core/)
- Database Models (db/)
- Authentication/Security
- Migration System (Alembic)

Database Section:
- Animals
- Events
- Users
- Groups
- Roles
- Permissions

##### Interaction Flows

- Frontend to Backend API calls
- Backend to Database interactions
- Authentication flows
- Email service integration

##### Specific Implementation Details

Technical stack badges:
- React/Vite
- FastAPI
- MySQL
- Tailwind CSS
- SQLAlchemy
- Pydantic

##### Key Features to Highlight

Specific flows for:
- Animal check-in/check-out system
- Multi-user management
- Department management
- Data export functionality
- Activity feed system

##### Security Layer

Highlight:
- JWT authentication
- Role-based access control
- Password reset flow
- Security middleware

For this specific project, emphasize the animal management workflows and multi-user aspects, as these are core features of the system. Also highlight the scalability aspects of the SaaS architecture, as this is designed to be self-hosted by different organizations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Frontend["Frontend Layer (React/Vite)"]
        direction TB
        UI["UI Components"]:::frontend
        Dashboard["Dashboard Components"]:::frontend
        Auth["Authentication Routes"]:::frontend
        Events["Event Management"]:::frontend
        Animals["Animal Management"]:::frontend
        Users["User Management"]:::frontend
        APIInt["API Integration Layer"]:::frontend
        State["State Management"]:::frontend
        Tables["Data Tables"]:::frontend
        Settings["Settings Management"]:::frontend
        Routes["Route Management"]:::frontend
    end

    subgraph Backend["Backend Layer (FastAPI)"]
        direction TB
        APIRoutes["API Routes"]:::backend
        Security["Security/Auth"]:::backend
        CoreServices["Core Services"]:::backend
        DBModels["Database Models"]:::backend
        Config["Configuration"]:::backend
        Schemas["Schema Definitions"]:::backend
        DBConn["Database Connection"]:::backend
        Dependencies["Dependencies"]:::backend
    end

    subgraph Database["Database Layer"]
        direction TB
        MySQL[(MySQL Database)]:::database
        Migrations["Alembic Migrations"]:::database
    end

    subgraph External["External Services"]
        direction TB
        EmailService["Email Service (hams-mails)"]:::external
    end

    %% Frontend Internal Connections
    UI --> Dashboard
    UI --> Auth
    UI --> Events
    UI --> Animals
    UI --> Users
    State --> APIInt
    Tables --> Dashboard
    Settings --> Dashboard
    Routes --> Dashboard

    %% Backend Internal Connections
    APIRoutes --> Security
    APIRoutes --> CoreServices
    CoreServices --> DBModels
    DBModels --> DBConn
    Security --> Dependencies
    Config --> CoreServices
    Schemas --> APIRoutes

    %% Cross-Layer Connections
    APIInt --> APIRoutes
    DBConn --> MySQL
    Migrations --> MySQL
    CoreServices --> EmailService

    %% Click Events
    click Dashboard "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/components/dashboard"
    click Auth "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/routes/auth"
    click Events "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/components/events"
    click Animals "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/routes/dashboard/animals"
    click Users "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/routes/dashboard/users"
    click UI "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/components/ui"
    click APIRoutes "https://github.com/tyball21/Open-HAMS/tree/meister/backend/api/routes"
    click Security "https://github.com/tyball21/Open-HAMS/blob/meister/backend/core/security.py"
    click DBModels "https://github.com/tyball21/Open-HAMS/tree/meister/backend/db"
    click Migrations "https://github.com/tyball21/Open-HAMS/tree/meister/backend/migrations"
    click APIInt "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/api"
    click EmailService "https://github.com/tyball21/Open-HAMS/tree/meister/hams-mails"
    click Config "https://github.com/tyball21/Open-HAMS/blob/meister/backend/core/config.py"
    click Tables "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/components/tables"
    click Schemas "https://github.com/tyball21/Open-HAMS/blob/meister/backend/schemas.py"
    click State "https://github.com/tyball21/Open-HAMS/blob/meister/frontend/src/api/queries.ts"
    click DBConn "https://github.com/tyball21/Open-HAMS/blob/meister/backend/core/db.py"
    click Settings "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/components/settings"
    click Dependencies "https://github.com/tyball21/Open-HAMS/blob/meister/backend/api/deps.py"
    click Routes "https://github.com/tyball21/Open-HAMS/tree/meister/frontend/src/routes"

    %% Styling
    classDef frontend fill:#3b82f6,color:white
    classDef backend fill:#22c55e,color:white
    classDef database fill:#eab308,color:white
    classDef external fill:#a855f7,color:white
    classDef security fill:#ef4444,color:white

    %% Legend
    subgraph Legend
        Frontend_L[Frontend Component]:::frontend
        Backend_L[Backend Component]:::backend
        Database_L[Database Component]:::database
        External_L[External Service]:::external
        Security_L[Security Component]:::security
    end
```
