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.
16 KiB
16 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: 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
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 via Tauri
- Desktop: Tauri 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
│ ├── 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