Ikamet OS is operational lifecycle infrastructure for expatriates in Türkiye. This document covers the high-level system design.
Design principles
Workflow-first. Every screen, every API endpoint, every database model exists to move a workflow forward or make its state visible.
Timeline-first. Every meaningful action writes a TimelineEvent. The timeline is the single source of truth for what happened, when, and who did it.
Provider abstraction. Frontend applications never call provider APIs directly. All provider interactions go through the adapter layer in app-api.
Public ID everywhere. No raw database integer IDs are exposed in URLs, APIs, or UI. All entities use prefixed public IDs (cus_xxx, ord_xxx, etc.).
Domain hierarchy
Authority / Acquisition
| Domain | Repo | Purpose |
|---|
| ikamet.com | site-ikamet | Immigration authority, SEO/AEO |
| ikametsigorta.com | site-ikametsigorta | Insurance authority, quote funnels |
| ikametstaff.com | site-ikametstaff | Employer/candidate onboarding |
Customer Application
| Domain | Repo | Purpose |
|---|
| app.ikamet.com | app-web | Intake, uploads, checkout, portal |
Operations
| Domain | Repo | Purpose |
|---|
| ops.ikamet.com | app-admin | Workflows, renewals, communications |
Orchestration
| Domain | Repo | Purpose |
|---|
| api.ikamet.com | app-api | Providers, queues, automations, AI |
Documentation
| Domain | Repo | Purpose |
|---|
| docs.ikamet.com | docs-ikamet | This site |
Stack
| Layer | Technology |
|---|
| Frontend (ops + web) | Next.js 14 · TypeScript · TailwindCSS · React Query · shadcn/ui |
| Authority sites | Astro · TailwindCSS · Cloudflare Pages |
| Backend | Node.js · Express · Prisma · PostgreSQL |
| Database | PostgreSQL (DigitalOcean managed) |
| Deployment | Cloudflare Pages (frontends) · DigitalOcean (backend) |
| Messaging | WhatsApp Cloud API · SendGrid · Twilio |
| Payments | Stripe · Wise |
| AI | OpenAI · Claude |
