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: Vitest + 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: No separate registry. Use Docker Compose networking as registry. Put services on the same Compose network. Call services by service name (DNS). Keep endpoints in env vars.
  Health Checks: HTTP /health endpoints. Add healthcheck + depends_on: condition: service_healthy to reduce startup race issues.
  Load Balancing: No load balancing
  
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**: Docker Compose 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 via Tauri
- **Desktop**: Tauri applications for major operating systems

### Infrastructure Technologies
```yaml
Containerization:
  Runtime: Docker 24+
  Orchestration: Docker Compose
  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
│   ├── 1_requirements/             # Functional and Non Functional requirements
│   ├── 2_architecture/             # Application architecture
│   │   ├── decisions/              # ADRs (Architecture Decision Records)
│   │   ├── diagrams/
│   │   └── api-specs/              # OpenAPI specs
│   └── 3_guidelines/               # Project guidelines including design guidelines
├── backend/
│   ├── tools/                      # Build tools, code generators
│   ├── services/                   # Microservices
│   │   ├── api-gateway/            # Entry point, routes to services
│   │   │   ├── cmd/
│   │   │   │   └── main.go
│   │   │   └── internal/
│   │   │       ├── config/
│   │   │       │   └── config.go
│   │   │       ├── routes/
│   │   │       │   └── router.go
│   │   │       └── proxy/
│   │   │           └── handlers.go
│   │   └── {service-name}/
│   │       ├── cmd/
│   │       │   └── main.go         # Service entry point
│   │       ├── config/             # Configuration management (Viper/env configuration)
│   │       ├── migrations/         # Ent's migration
│   │       ├── internal/
│   │       │   ├── handlers/       # Fiber HTTP handlers
│   │       │   ├── app/            # Business logic (commands, queries, dto)
│   │       │   │   ├── command/
│   │       │   │   ├── query/
│   │       │   │   └── dto/
│   │       │   ├── domain/         # Domain logic in pure Go (Domain Driven Design)
│   │       │   │   ├── model/      # Aggregates and Value objects
│   │       │   │   ├── repository/ # Reponsitory interfaces
│   │       │   │   ├── service/    # Services
│   │       │   │   └── events/     # events
│   │       │   ├── infra/ 
│   │       │   │   └── ent/        # Ent models and schemas + repositories implementation
│   │       │   │   │   ├── model/  # Ent models and schemas
│   │       │   │   │   │   ├── schema/
│   │       │   │   │   │   ├── generate.go   # //go:generate directive
│   │       │   │   │   │   └── ... (generated)
│   │       │   │   │   ├── repository/  # Implements domain interface
│   │       │   │   │   └── mapper/ # ent to domain mapper
│   │       │   │   │
│   │       │   │   └── cache/
│   │       │   └── interfaces/     # Interface adapters (HTTP, gRPC)
│   │       │       ├── events/
│   │       │       ├── api/        # API definitions (OpenAPI/gRPC)
│   │       │       └── http/
│   │       │           ├── handlers/ # Fiber HTTP handlers
│   │       │           └── middleware/
│   │       └── tests/              # Service-specific tests
│   └── shared/                 # Shared packages
│       ├── domain/ 
│       │   ├── errors/         # Shared domain errors
│       │   ├── events/         # Domain events contracts
│       │   ├── types/          # Shared types
│       │   └── valueobjects/   # Shared value objects
│       └── infra/ 
│           ├── auth/           
│           │   ├──  zitadel/   # JWT middleware & Zitadel integration
│           │   └──  rbac/
│           ├── database/       # Ent database client
│           │   ├──  postgres/
│           │   └──  redis/
│           ├── observability/  # Metrics and tracing
│           │   ├──  logging/   # Structured logging
│           │   ├──  tracing/   # OpenTelemetry 
│           │   └──  metrics/   # Prometheus 
│           ├── security/       # Security utilities
│           └── utils/          # Common utilities like httputil (errors, pagintaion, response)
│
├── frontend/
│   ├── shared/
│   │   ├── ui-components/          # Shared UI components
│   │   ├── logic/                  # Business logic
│   │   ├── types/                  # TypeScript types
│   │   └── utils/                  # Utility functions
│   └── apps/
│       ├── web/                    # SolidJS web app (Vite + TypeScript)
│       │   ├── package.json
│       │   ├── vite.config.ts
│       │   ├── index.html
│       │   ├── public/
│       │   ├── src/
│       │   │   ├── main.tsx
│       │   │   ├── App.tsx
│       │   │   ├── routes/
│       │   │   ├── layouts/
│       │   │   ├── features/       # Feature-based organization
│       │   │   ├── hooks/          # App-specific hooks
│       │   │   ├── utils/
│       │   │   └── styles/
│       │   │       └── global.css
│       │   └── tsconfig.json
│       └── cross-platform/         # Tauri app
│           ├── package.json
│           ├── vite.config.ts
│           ├── src/                # Inherits most from web app
│           │   ├── main.tsx
│           │   ├── App.tsx         # May wrap web App with desktop-specific logic
│           │   └── platform/       # Desktop-specific code
│           │
│           ├── src-tauri/           # Rust/Tauri native code
│           │   ├── Cargo.toml
│           │   ├── tauri.conf.json
│           │   ├── capabilities/
│           │   ├── icons/
│           │   ├── src/
│           │   │   ├── main.rs
│           │   │   ├── lib.rs
│           │   │   ├── commands/    # Tauri commands (Rust ↔ JS bridge)
│           │   │   └── plugins/
│           │   └── build.rs
│           └── tsconfig.json
│
└── infrastructure/                 # DevOps and deployment
    ├── dev/                        # Development setup
    │   ├── docker-compose.yml      # dev stack (hot reload, mounts)
    │   └── api.env                 # dev env vars
    └── prod/                       # Production setup
    │   ├── docker-compose.yml      # prod stack 
    │   └── api.env                 # prod env vars
    └── services/                   # Dockerfiles
```