You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
14 KiB
14 KiB
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
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
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
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
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
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
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