# stoyanoff2020/bakery-crm-erp architecture

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

- Interactive diagram: https://gitdiagram.com/stoyanoff2020/bakery-crm-erp
- Repository: https://github.com/stoyanoff2020/bakery-crm-erp

## Overview

##### Project type and purpose
- This is a full-stack, multi-tenant CRM/ERP for bakery businesses, composed of three primary services (frontend, backend, AI service) plus shared libraries, orchestrated via Docker/Kubernetes, with CI/CD pipelines and monitoring.

##### File structure
- Top-level directories:
- packages/frontend (React/TypeScript PWA)
- packages/backend (Node.js/Express/TypeScript API)
- packages/ai-service (Python/FastAPI machine-learning endpoints)
- packages/shared (TypeScript types and utilities)
- Configuration/deployment:
- docker-compose.yml and monitoring variant
- k8s manifests under k8s/staging
- CI/CD workflows in .github/workflows
- Scripts: quick-start.sh, backup/restore scripts, comprehensive test harness

##### Pull architecture insights from README
- Frontend uses Vite, React Context, Tailwind CSS, PWA features.
- Backend uses Express, JWT, PostgreSQL, Swagger docs, multi-tenant via row-level security.
- AI service uses FastAPI, Scikit-learn, async endpoints.
- PostgreSQL is the central data store (single database with row-level security).
- Monitoring/backup via scripts, Prometheus/Grafana likely (docker-compose.monitoring.yml).

##### Main components and interactions
a. Components
1. Client (Browser/Mobile PWA)
2. Frontend App (React + Service Worker)
3. API Gateway / Load Balancer (NGINX or Cloud LB)
4. Backend Service (Express/TypeScript)
5. AI Service (FastAPI/Python)
6. Shared Type Library (consumed at build time by front/backend)
7. PostgreSQL Database (single instance or cluster)
8. CI/CD Pipeline (GitHub Actions)
9. Monitoring & Logging (Prometheus, Grafana, ELK, custom scripts)
10. External Services: SMTP/email provider, third-party analytics, optional payment gateways

b. Relationships & Data Flows
- Browser ↔ Frontend: HTTPS, JWT stored in localStorage or cookie
- Frontend ↔ API Gateway: REST calls to /api/*
- API Gateway ↔ Backend: Routes mapped to controllers, middleware for auth, rate-limit, etc.
- Backend ↔ PostgreSQL: read/write via connection pool; migrations managed by scripts
- Backend ↔ AI Service: HTTP calls to /ai-service endpoints for forecasting, optimization
- AI Service ↔ PostgreSQL: read analytics tables; populate insights
- Backend ↔ External Services: email service, audit logging, monitoring endpoints
- CI/CD → Kubernetes: automated build, test, and deploy of Docker images

c. Architectural patterns & principles
- Monorepo with Turborepo: shared code, single build root
- Micro-services / modular services: clear separation of frontend, backend, AI
- Multi-tenant via row-level security in PostgreSQL
- API-first design: OpenAPI/Swagger for backend, auto-docs for AI service
- PWA for offline support and mobile UX
- Infrastructure as Code: Docker compose for dev, Kubernetes manifests for staging/production
- Comprehensive automated testing at unit, integration, e2e, security, performance levels

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        Browser["Browser/Mobile PWA"]:::frontend
    end

    subgraph "API Layer"
        APIGateway["API Gateway / Load Balancer\n(NGINX)"]:::infra
    end

    subgraph "Services Layer"
        FE["Frontend App\n(React/TypeScript PWA)"]:::frontend
        BE["Backend Service\n(Node.js/Express)"]:::service
        AI["AI Service\n(Python/FastAPI)"]:::service
    end

    subgraph "Build-Time Shared"
        Shared["Shared Type Library"]:::infra
    end

    subgraph "Data Layer"
        DB["PostgreSQL\n(single instance with RLS)"]:::db
    end

    subgraph "Infrastructure"
        CI1["GitHub Actions CI\n(ci.yml)"]:::infra
        CI2["GitHub Actions CD\n(ci-cd.yml)"]:::infra
        DCDev["Docker Compose (dev)"]:::infra
        DCMon["Docker Compose (monitoring)"]:::infra
        K8s["Kubernetes Manifests\n(staging)"]:::infra
        Scripts["Monitoring & Logging Scripts"]:::infra
        Setup["CI/CD Setup Script"]:::infra
        Quick["Quick-start Utility Script"]:::infra
    end

    Browser -->|"HTTPS (PWA)"| FE
    FE -->|"HTTP/REST /api/*"| APIGateway
    APIGateway -->|"Routes"| BE
    BE -->|"PostgreSQL queries"| DB
    BE -->|"HTTP/REST /ai-service"| AI
    AI -->|"Analytics Queries"| DB

    Shared -->|"types at build"| FE
    Shared -->|"types at build"| BE
    Shared -->|"types at build"| AI

    Setup -->|"Configure workflows"| CI1
    CI1 -->|"Trigger CD"| CI2
    CI2 -->|"Deploy to cluster"| K8s

    Quick -->|"Launch dev stack"| DCDev
    DCDev -->|"Includes services"| FE
    DCDev -->|"Includes services"| BE
    DCDev -->|"Includes services"| AI

    Scripts -->|"Start monitoring"| DCMon
    DCMon -->|"Collect metrics"| Scripts

    click FE "https://github.com/stoyanoff2020/bakery-crm-erp/tree/main/packages/frontend"
    click BE "https://github.com/stoyanoff2020/bakery-crm-erp/tree/main/packages/backend"
    click AI "https://github.com/stoyanoff2020/bakery-crm-erp/tree/main/packages/ai-service"
    click Shared "https://github.com/stoyanoff2020/bakery-crm-erp/tree/main/packages/shared"
    click CI1 "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/.github/workflows/ci-cd.yml"
    click DCDev "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/docker-compose.yml"
    click DCMon "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/docker-compose.monitoring.yml"
    click K8s "https://github.com/stoyanoff2020/bakery-crm-erp/tree/main/k8s/staging"
    click Scripts "https://github.com/stoyanoff2020/bakery-crm-erp/tree/main/scripts"
    click APIGateway "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/packages/frontend/nginx.conf"
    click Setup "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/setup-github.sh"
    click Quick "https://github.com/stoyanoff2020/bakery-crm-erp/blob/main/quick-start.sh"

    classDef frontend fill:#8fbc8f,stroke:#333,stroke-width:1px;
    classDef service fill:#1e90ff,stroke:#333,stroke-width:1px;
    classDef db fill:#f4d03f,stroke:#333,stroke-width:1px;
    classDef infra fill:#a9a9a9,stroke:#333,stroke-width:1px;
```
