# 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 │ ├── 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 (embeds the SolidJS web 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 ```