Tenafriq is a microservice ecosystem designed to unify property management, access control, equipment logistics, workforce orchestration, inventory, point‑of‑sale, and supply chain. The platform serves thousands of concurrent residents, staff, and POS terminals with strict consistency requirements and real‑time hardware integration.
graph TD
Client["Web/Mobile/POS Terminal"]
APIG["API Gateway (Kong)"]
Services["resident-core | facility-access | equipment-checkout | workforce-mgmt | inventory-core | pos | supply-chain"]
CorePkg["tq_core (shared pip package)"]
DB[("PostgreSQL Cluster")]
Cache[("Redis Cluster")]
MQ[("RabbitMQ")]
Client -->|HTTPS + JWT| APIG
APIG -->|proxy + auth| Services
Services -->|import| CorePkg
Services --> DB
Services --> Cache
Services -->|async events| MQ
MQ -.-> Services
The gateway terminates TLS, validates JWT (using tq_core's verification), and applies per‑service rate limits. Each service owns its database schemas, while Redis provides distributed locks (locker codes, inventory holds) and session storage for suspended POS transactions.
tq_core is a pip‑installable Python package pinned to a single version across all services. It provides common infrastructure to reduce duplication and guarantee consistency.
| Module | Responsibility |
|---|---|
core.config | Pydantic settings loader with env overrides for each service |
core.auth | JWT creation/validation, bcrypt hashing, permission helper (RBAC) |
core.db | Async SQLAlchemy engine, session + transaction middleware |
core.middleware | Request ID, structured logging, global error handling |
core.events | Typed event publisher (RabbitMQ) with retry logic |
core.models.base | Base ORM (UUID, soft‑delete, optimistic lock version) |
core.schemas | Pydantic v2 pagination, audit fields, common DTOs |
Manages leases, rent/fee payments, maintenance requests, referrals, community boards, and unit/floor inventory. Slow‑changing compliance data, high legal integrity.
| Method | Endpoint | Description |
|---|---|---|
POST | /leases/{id}/pay | Record rent payment (idempotent key) |
GET | /maintenance/requests | List with filters (unit, status) |
POST | /referrals | Resident referral tracking |
Real‑time concurrency for locker/spots, event bookings, QR/card check‑in, membership management, hardware integration (door readers, smart locks).
Checkout/return with due dates, late fees, maintenance status, and reservation holds. High transactional volume (gym gear, AV equipment).
| Endpoint | Description |
|---|---|
POST /checkout | Reserve + mark out, decrement available stock |
Complex rules engine: shift scheduling, timecard with rounding, time‑off requests, drop/pick shifts, min/max hour enforcement, audit trail for labor laws.
Product catalog, tax categories, discounts (cart/product), stock levels, low‑stock alerts. Source of truth for all items sold via POS and used in supply chain.
High‑throughput, stateful cart sessions. Suspend/resume with recall ID, barcode scan → add to cart, dynamic offer application, shift/day closing with financial reconciliation.
Vendor management, auto‑PO generation based on reorder points, stock inbound/outbound, receiving validation, integration with distributor APIs.
sequenceDiagram
participant C as Client
participant G as API Gateway
participant A as auth-service (internal)
participant Core as tq_core
participant S as Target Service
C->>G: POST /auth/login (email/password)
G->>A: forward
A->>Core: verify_password()
Core-->>A: valid
A->>Core: create_access_token()
Core-->>A: JWT
A-->>G: tokens
G-->>C: access/refresh tokens
C->>G: GET /residents (Bearer)
G->>S: forward with token
S->>Core: decode+verify JWT, extract user
Core-->>S: UserContext
S->>S: RBAC check (role: resident/staff/manager)
S-->>G: response
G-->>C: data
Read‑heavy operations use synchronous gRPC/HTTP calls with < 50ms budget. State changes that require cross‑service consistency (e.g., stock reservation → inventory update) are event‑driven via RabbitMQ.
graph LR
POS[POS Service] -->|reserve items| Inventory[Inventory Core]
Inventory -->|StockLevelChanged| MQ[RabbitMQ]
MQ --> SupplyChain[Supply Chain]
MQ --> FacilityAccess[Facility Access]
FacilityAccess -->|checkout complete| Equipment[Equipment Checkout]
Each service owns dedicated PostgreSQL schemas. Cross‑service reads use eventual consistency through materialized views or API calls. The shared Redis cluster caches rate limits, JWT revocation, and session data.
POS "suspend" cart → stored in Redis with TTL. Late fee calculation runs as a scheduled job reading from resident‑core and equipment‑checkout.
graph TD
Ingress["Ingress (nginx)"]
GW["API Gateway Pods (3 replicas)"]
NS["tenafriq Namespace"]
SVC1["resident-core (HPA: 5-20)"]
SVC2["facility-access (HPA: 3-15)"]
DBCluster["StatefulSet PostgreSQL + read replicas"]
RedisCluster["Redis Sentinel"]
MQCluster["RabbitMQ quorum queue"]
Ingress --> GW
GW --> SVC1 & SVC2
SVC1 --> DBCluster
SVC2 --> RedisCluster
| Service | Replicas (min/max) | CPU req/limit | Memory |
|---|---|---|---|
| resident-core | 4/15 | 0.6 / 2.0 | 1Gi / 2Gi |
| pos-service | 6/25 | 0.8 / 2.5 | 1.5Gi / 3Gi |
| supply-chain | 2/10 | 0.5 / 1.5 | 1Gi / 2Gi |
| Category | Choice | Justification |
|---|---|---|
| API Framework | FastAPI (Python 3.11+) | Async native, Pydantic v2, automatic OpenAPI |
| Shared Library | tq_core (private PyPI) | Zero‑copy auth, config, DB session reuse across 7 services |
| Database | PostgreSQL 15 (asyncpg) | ACID, JSONB for flexible attributes, row‑level locking |
| Message Broker | RabbitMQ (mirrored queues) | Reliable delivery, dead‑letter for retries |
| Cache | Redis 7 | Rate limiting, distributed locks, POS cart state |
| API Gateway | Kong (PostgreSQL backend) | JWT validation, rate limiting, plugin extensibility |
| Orchestration | Kubernetes (EKS/AKS) | Auto‑scaling, self‑healing, rolling updates |
| Observability | OpenTelemetry + Prometheus + Grafana | Trace propagation, custom metrics (checkout latency, stock events) |
This section is a stub. Once the following information becomes available, it will cover:
- Distributed tracing policy with OpenTelemetry sampling (1% for reads, 100% for checkout/POS transactions)
- Centralized secret management (HashiCorp Vault) and rotation strategy
- Global rate limiting per resident tier and per IP for public endpoints
- Audit trail design for financial operations and workforce timecards
- TLS 1.3 end‑to‑end between clients and API gateway, mTLS between services using Istio or linkerd.
- JWT short lifetime (15 min) + refresh token rotation stored in Redis.
- RBAC model: resident, staff, facility manager, admin. API Gateway rejects unauthorized requests.
- Network policies: deny ingress between services except via gateway and internal event bus.
| Failure | Probability | Impact | Mitigation |
|---|---|---|---|
| PostgreSQL primary outage | Low | High (all writes) | Automated failover to replica (< 60s), read replicas serve queries during switch |
| facility-access service crash | Medium | Medium (no new check‑ins) | Circuit breaker, local hardware cache (offline QR mode via sync token) |
| RabbitMQ queue backpressure | Medium | Medium | Dead‑letter queues, backpressure triggers autoscaling of consumers, alert on queue depth >10k |
| POS suspend session loss | Low | Low | Persist cart state to Redis with replication + hourly backup snapshot |
| Distributed lock deadlock (locker) | Low | Low | Redlock algorithm with fallback TTL (30s), manual unlock endpoint for staff |
This section is a stub. Once the following information becomes available, it will cover:
- Multi‑region deployment strategy for diaspora or large portfolio of properties
- Offline capability for facility doors and POS during WAN outage
- Integration with third‑party ERP for accounting (QuickBooks / SAP)
- Data retention policy for workforce timecards (7 years compliance)