Tech Stack Overview¶
KanjiIQ is built with a self-hosted, open-source-first philosophy. Every component runs on infrastructure we control, with no vendor lock-in.
Technology Summary¶
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Flutter Web | Cross-platform UI framework |
| Backend | Dart Frog | Lightweight REST API server |
| Database | PostgreSQL 15 | Primary data store with JSONB |
| Translation | OpenAI API | Dynamic content translation |
| Orchestration | k3s (Kubernetes) | Container orchestration |
| Ingress | Traefik | Reverse proxy, TLS termination, rate limiting |
| TLS | cert-manager + Let's Encrypt | Automated SSL certificate management |
| CI/CD | Forgejo Actions | Build, push, and deploy automation |
| Container Registry | Forgejo Container Registry | Docker image storage |
| Version Control | Forgejo (Gitea fork) | Self-hosted Git platform |
| Hosting | Hetzner Dedicated Server | Infrastructure provider |
| Admin | Flutter Web | Admin dashboard for locale/analytics management |
Why These Choices?¶
Dart Everywhere¶
The most distinctive architectural choice is using Dart for both frontend and backend:
- Flutter (Dart) for the frontend
- Dart Frog (Dart) for the backend
This enables:
- Shared model definitions between client and server
- Single language expertise for the entire team
- Consistent tooling (Dart analyzer, formatter, test framework)
- Potential for shared business logic packages
Self-Hosted Stack¶
KanjiIQ deliberately avoids managed cloud services in favor of self-hosted alternatives:
| Managed Service | KanjiIQ Uses | Benefit |
|---|---|---|
| GitHub/GitLab | Forgejo | Full control, no per-user pricing |
| Docker Hub | Forgejo Container Registry | Co-located with source code |
| GitHub Actions | Forgejo Actions | Same YAML syntax, self-hosted runners |
| AWS RDS | PostgreSQL on k8s | No per-hour database charges |
| AWS ALB | Traefik | Built into k3s, free |
| AWS ACM | cert-manager + Let's Encrypt | Free TLS certificates |
Cost Efficiency¶
The entire production stack runs on a single Hetzner dedicated server, keeping monthly costs predictable and significantly lower than equivalent cloud-managed services. See Infrastructure for details.
Architecture Principles¶
- Container-first: Every component is containerized with multi-stage Docker builds
- Infrastructure as code: All Kubernetes manifests are version-controlled
- Non-root execution: All containers run as UID 1000 for security
- Health checks: Every container has liveness and readiness probes
- Offline-capable: The frontend works without internet via local SQLite cache
- Privacy-conscious: GDPR/CCPA-compliant analytics with auto-anonymization