Teikei

Teikei is a self‑hosted, monorepo SaaS stack that serves as both a public map of community‑supported agriculture (CSA) operations across Germany, Switzerland and Austria, and a programmable API for data ingestion, querying and administration. From a developer’s standpoint it is an opinionated but modular architecture that bundles three distinct concerns – data, presentation and administration – into a single code base while keeping the interfaces cleanly separated. The core data layer is a PostgreSQL database accessed through a FeathersJS service layer, exposing a JSON‑REST API that can be consumed by any client. The front‑end is a React/Redux SPA that talks to the API via feathers‑client and Leaflet, while the admin UI is a CRUDL.io dashboard that mirrors the same API under separate routes. The entire stack is orchestrated with npm workspaces and Lerna, allowing a single npm run dev command to spin up the API, Map and Admin services along with a Dockerised PostgreSQL instance for local development.

Technical Stack & Architecture

• Backend: Node ≥ 18, FeathersJS (Express‑based) with node‑schedule for background jobs.
• Database: PostgreSQL ≥ 9.5, accessed via Feathers services; schema is versioned with migration scripts bundled in the repo.
• Frontend: React 18 (CRA + Sass), Redux for state, Leaflet for map rendering, feathers‑client for real‑time sync.
• Admin: CRUDL.io – a declarative admin framework that auto‑generates CRUD routes and UI components from Feathers services.
• Build & DevOps: npm workspaces, Lerna for workspace coordination, Docker Compose for dev DB, GitHub Actions CI pipelines (Map, API, Admin).
• Packaging: The repo is a monorepo; each module (/api, /map, /admin) can be published separately if needed, but the default build script bundles them into a single deployable stack.

Core Capabilities & APIs

• REST + Socket.io: Feathers automatically provides REST endpoints and optional real‑time updates via websockets for all services.
• Job Queue: node-schedule is used for cron‑like background tasks (e.g., data enrichment, cache invalidation).
• Validation: Joi schemas are defined per service; both client and server enforce the same contracts, reducing data‑quality errors.
• Admin API: Separate endpoints (/admin/*) expose CRUD operations with role‑based access control, allowing external tools to programmatically manage records.
• Extensibility Hooks: Feathers hooks (before/after) can be added to services for custom business logic, authentication, or audit logging.
• Webhooks: The API can emit events that external services can subscribe to via Socket.io or custom webhook endpoints.

Deployment & Infrastructure

Teikei is designed for self‑hosting on any environment that supports Node and PostgreSQL. The recommended stack uses Docker Compose to spin up the API, Map and Admin services along with a PostgreSQL container. For production, each service can be deployed independently (e.g., API on a Node PaaS, Map and Admin on static hosts) as long as they share the same database. The monorepo’s Lerna scripts support building Docker images per module, enabling CI/CD pipelines that push to container registries. Horizontal scaling of the API is straightforward: Feathers services are stateless, so you can run multiple instances behind a load balancer and use a shared PostgreSQL cluster or a cloud‑managed Postgres service.

Integration & Extensibility

• Plugin System: Feathers’ modular architecture allows developers to drop in new services or replace existing ones without touching the core code.
• Custom Hooks: Add authentication, rate‑limiting or logging by writing small JavaScript functions that run before/after service calls.
• Third‑Party Auth: Feathers supports OAuth, JWT, LDAP out of the box; integrating a SAML provider is just a matter of adding an authentication hook.
• Data Import: The API exposes bulk endpoints and CSV parsing utilities, making it easy to ingest data from spreadsheets or other CSA platforms.
• Map Customization: The React SPA is built with create‑react‑app, so adding new map layers, custom markers or filters can be done by extending the Redux store and Leaflet components.

Developer Experience

• Configuration: A single .env file at the repo root holds all environment variables for API, Map and Admin. The sample file (.env.sample) documents required keys such as DATABASE_URL, PORT and Feathers authentication secrets.
• Documentation: The README provides a concise walk‑through, and the Feathers services expose Swagger UI when enabled. CRUDL.io auto‑generates API docs for admin routes.
• Community & Support: The project is open source on GitHub, with active CI pipelines and issue tracking. While the user base is niche (CSA communities), the tech stack is mainstream, so developers can rely on Node/React/Feathers ecosystems for help.
• Testing: Each module contains unit tests (Mocha/Chai) and integration tests that run in CI; developers can add their own test suites easily.

Use Cases

1. CSA Operator – Host the map and API on a small VPS to expose farm plots, harvest schedules and membership forms.
2. **Local