knowfoolery/docs/2_architecture/application-architecture.md

# Know Foolery - Application Architecture Documentation

## Application Architecture Overview

Know Foolery follows a microservices architecture with clear separation between frontend presentation, backend services, and data persistence layers. The system is designed for cross-platform compatibility, scalability, and maintainability.

### Frontend Architecture
- **Web Application**: Responsive web application
- **Mobile Applications**: Cross platform application for iOS and Android. Packages the web application 
- **Desktop Applications**: Cross platform application for MacOS, Windows and Linux. Packages the web application 

### Backend Architecture
- **Business Logic**: Domain Driven Design approach 
- **Microservices**: Services with clear domain boundaries
- **API Gateway**: Centralized routing, authentication, and rate limiting
- **Database ORM**: For type-safe database operations
- **Communication**: gRPC for inter-service synchronous communication 
- **External APIs**: Repository pattern for external integrations

### External Services
- **Authentication**: OAuth 2.0/OIDC authentication
- **Relational Database**: For production application data
- **Cache**: Session state and caching layer


## System Architecture Diagram

```
┌────────────────────────────────────────────────────────────────────────────┐
│                            Client Layer                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  ┌─────────────┐    │
│  │   Web App    │  │  Mobile iOS  │  │ Mobile Android│  │   Desktop   │    │
│  └──────────────┘  └──────────────┘  └───────────────┘  └─────────────┘    │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                               HTTPS/WSS
                                      │
┌─────────────────────────────────────────────────────────────────────────────┐
│                          API Gateway Layer                                  │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  NGINX + API Gateway Service (Go)                                      │ │
│  │  • Authentication & Authorization                                      │ │
│  │  • Rate Limiting & CORS                                                │ │
│  │  • Request Routing & Load Balancing                                    │ │
│  │  • Security Headers & Input Validation                                 │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                 gRPC/HTTP
                                      │
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Microservices Layer                                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                              Database Connections
                                      │
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Data & External Layer                               │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ ┌───────────────┐       │
│  │   Primary   │ │   Cache &   │ │ Authentication │ │ Observability │       │
│  │  Database   │ │  Sessions   │ │    Provider    │ │      Stack    │       │
│  └─────────────┘ └─────────────┘ └────────────────┘ └───────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Frontend Technologies
```yaml
Web Application:
  Framework: SolidJS 1.9.3+
  Language: TypeScript 5.0+
  Build Tool: Vite 4.0+
  UI Library: SUID (suid.io)
  Testing: Jest + Playwright

Mobile Applications:
  Framework: Tauri 2.9.5+
  Language: TypeScript
  Package manager: yarn
  UI Template: Solid

Desktop Application:
  Framework: Tauri 2.9.5+
  Language: TypeScript
  Package manager: yarn
  UI Template: Solid
```

### Backend Technologies
```yaml
Microservices:
  Language: Go 1.25+
  HTTP Framework: Fiber 3.0+
  gRPC: Protocol Buffers + gRPC-Go
  Database ORM: Ent (Facebook)
  Authentication: JWT + Zitadel Integration
  Testing: Go testing + testcontainers
  
API Gateway:
  Reverse Proxy: NGINX
  Gateway Service: Go + Fiber
  Load Balancing: Round-robin + Health checks
  Rate Limiting: Redis-based sliding window
```

### Data Technologies for production
```yaml
Primary Database:
  Engine: PostgreSQL 15+
  Connection Pooling: pgxpool
  Migrations: Ent migrations
  Backup: pg_dump + Object Storage

Cache and Session:
  Engine: Redis 7+
  Use Cases: Sessions, Rate limiting, Cache
  Clustering: Redis Cluster (Production)
  Persistence: RDB + AOF

Authentication:
  Provider: Zitadel (Self-hosted)
  Protocol: OAuth 2.0 + OpenID Connect
  Tokens: JWT with RS256 signing
  MFA: TOTP + WebAuthn
```

### Data Technologies for development
```yaml
Primary Database:
  Engine: Sqlite
  Migrations: Ent migrations

Cache Layer:
  Engine: Mock object created for the project

Authentication:
  Provider: Mock object created for the project
  Protocol: OAuth 2.0 + OpenID Connect
  Tokens: JWT with RS256 signing
```

### Inter-Service Communication
Service Mesh Architecture
```yaml
Communication Patterns:
  Synchronous: gRPC for real-time operations
  Asynchronous: asynchronous gRPC calls (Event-driven via message queues in the future)
  
Service Discovery:
  Registry: Kubernetes DNS
  Health Checks: HTTP /health endpoints
  Load Balancing: Round-robin with health awareness
  
Circuit Breaker:
  Pattern: Hystrix-style circuit breakers
  Fallback: Graceful degradation
  Timeout: Context-based timeouts
```

## Deployment & Infrastructure

### Development Environment
- **Local Development**: SQLite for rapid iteration
- **Docker Compose**: Containerized development environment
- **Testing**: Comprehensive unit, integration, and E2E testing

### Production Environment
- **Container Orchestration**: Kubernetes for production deployment
- **Database**: PostgreSQL with high availability configuration
- **Monitoring**: Prometheus, Grafana, Jaeger for observability
- **CI/CD**: GitHub Actions for automated testing and deployment

### Cross-Platform Deployment
- **Web**: Standard web application deployment
- **Mobile**: iOS App Store and Google Play Store distribution
- **Desktop**: Wails applications for major operating systems

### Infrastructure Technologies
```yaml
Containerization:
  Runtime: Docker 24+
  Orchestration: Kubernetes 1.28+
  Registry: Private Docker Registry
  
Observability:
  Metrics: Prometheus + Node Exporter
  Visualization: Grafana + Custom Dashboards
  Tracing: Jaeger + OpenTelemetry
  Logging: Structured logging + Loki
  
CI/CD:
  Platform: GitHub Actions
  Testing: Automated test suites
  Security: SAST/DAST scanning
  Deployment: GitOps with ArgoCD
```

## Project Structure
```
knowfoolery/
├── docs/                           # Project documentation
├── backend/
│   ├── services/                   # Microservices
│   │   ├── {service-name}/
│   │   │   ├── cmd/
│   │   │   │   └── main.go         # Service entry point
│   │   │   ├── internal/
│   │   │   │   ├── handlers/       # Fiber HTTP handlers
│   │   │   │   ├── app/            # Business logic (commands, queries, dto)
│   │   │   │   ├── domain/         # Domain logic (aggregates, value objects, repositories interfaces, services from Domain Driven Design)
│   │   │   │   ├── infra/ 
│   │   │   │   │   ├── events/
│   │   │   │   │   ├── grpc/
│   │   │   │   │   └── ent/        # Ent models and schemas + repositories implementation
│   │   │   ├── api/                # API definitions (OpenAPI/gRPC)
│   │   │   ├── config/             # Configuration management
│   │   │   ├── tests/              # Service-specific tests
│   │   │   ├── Dockerfile          # Container definition
│   │   │   └── go.mod              # Go module
│   │   └── shared/                 # Shared packages
│   │   │   ├── errors/             # Shared domain errors
│   │   │   ├── events/             # Domain events contracts
│   │   │   ├── types/              # Shared types
│   │   │   ├── valueobjects/       # Shared value objects
│   │   │   └── infra/ 
│   │   │       ├── auth/           # JWT middleware & Zitadel integration
│   │   │       ├── observability/  # Metrics and tracing
│   │   │       ├── security/       # Security utilities
│   │   │       └── utils/          # Common utilities
├── frontend/
│   ├── shared/
│   │   ├── ui-components/          # Shared Gluestack UI components
│   │   ├── logic/                  # Business logic
│   │   ├── types/                  # TypeScript types
│   │   └── utils/                  # Utility functions
│   └── apps/
│       ├── web/                    # React web app
│       ├── mobile/                 # React Native app
│       └── desktop/                # Wails desktop app
└── infrastructure/                 # DevOps and deployment
    ├── dev/                        # Development setup
    │   ├── docker-compose.yml      # dev stack (hot reload, mounts)
    │   └── api.env                 # dev env vars
    └── prod/                       # Production setup
```

### Backend Directory Structure
```
backend/
├── Domain/                     # Domain logic (DDD patterns)
├── services/                   # Microservices
│   ├── {service-name}/
│   │   ├── cmd/main.go         # Service entry point
│   │   ├── internal/
│   │   │   ├── handlers/       # Fiber HTTP handlers
│   │   │   ├── app/            # Business logic
│   │   │   ├── middleware/     # Service-specific middleware
│   │   │   └── models/         # Ent models and schemas
│   │   ├── config/             # Configuration management
│   │   └── tests/              # Service-specific tests
│   └── shared/                 # Shared packages
│       ├── auth/               # JWT & Zitadel integration
│       ├── database/           # Ent database client
│       ├── observability/      # Metrics and tracing
│       └── security/           # Security utilities
```

### Frontend Structure
```
frontend/
├── shared/
│   ├── ui-components/          # Shared Gluestack UI components
│   ├── logic/                  # Business logic
│   ├── types/                  # TypeScript types
│   └── utils/                  # Utility functions
└── apps/
    ├── web/                    # SolidJS web app (Vite + TypeScript)
    └── cross-platform/         # Tauri app (embeds the SolidJS web app)
```

### Infrastructure Structure
```
Infrastructure/
├── dev/                        # Scripts to setup and start development infrastructure
└── prod/                       # Scripts to setup and start production infrastructure
```