Architecture

Code Architecture

Monorepo layout and technical stack. Product decisions (v1 scope, tenancy, policies) are in Product Scope and linked docs from the repository README.

Repository layout

Path	Stack	Role
api/	Laravel	GraphQL API, REST endpoints, queues, auth
ui/	Vue 3	Web application (Vite SPA)
www/	Astro	Marketing site — static, public, separate deploy
docs/	Astro + Starlight	Public documentation — static, GitLab Pages
mobile/	Kotlin Multiplatform	Android, iOS; optional desktop exploration

Marketing site is not in ui/ — separate deployment (Product Scope, Security and Privacy).

API (api/)

• Framework: Laravel.
• Primary client API: GraphQL (Lighthouse).
• Also REST for webhooks, health, and concerns that do not fit GraphQL cleanly (graphql_plus_rest).
• Auth: Laravel Sanctum; SPA uses HttpOnly cookies; mobile uses token-based Sanctum flow.
• OAuth: Google, Apple (Socialite); church SSO later.
• Real-time: GraphQL subscriptions / WebSockets (notifications; mentor chat when mentorship ships).
• Note sync: CRDT merge via push/pull mutations; see Sync and Offline.
• Uploads (later): presigned object storage + file_id; see Files and Uploads.
• Database: PostgreSQL; PostgreSQL FTS for search in v1.
• Queues: Redis; Horizon or custom admin UI for job visibility.
• Permissions: ABAC policies in application code (see Identity and Access).
• Feature flags: DB-backed, polymorphic (user, group, church).
• Schema changes: avoid breaking changes; enforce minimum mobile app version when required.

GraphQL clients

• TypeScript (ui): GraphQL Code Generator.
• Kotlin (mobile): Apollo Kotlin (consistent client stack).

AI / MCP

• Study plan template MCP — shipped for platform admins (Operator guide); same capabilities as admin UI AI flows.
• End-user study assistant MCP — deferred; moderation and hosted/self-hosted AI details in AI Guidelines.

UI (ui/)

• Vue 3 (Composition API), TypeScript.
• Vite SPA (no SSR in app shell).
• State: Pinia.
• Server state: TanStack Query.
• Routing: vue-router v5 file-based routes (vue-router/vite, src/pages/).
• Tooling: ESLint, Prettier, Storybook, lodash.
• i18n: English v1; structure for future locales.
• Accessibility: improve where practical; checklist in code review (Security and Privacy).

Marketing site (www/)

Public pages only: landing, product story, pricing (if any), legal, links into ui/ for sign-in. No authenticated features; no API dependency for core pages.

• Generator: Astro — static HTML by default; content in Markdown or .astro pages.
• Vue: @astrojs/vue for islands only where interactivity is needed (e.g. a small demo widget). Most marketing pages stay zero-JS Astro components.
• Why Astro: marketing-first layouts (hero, sections, custom brand) without fighting a docs theme; fast builds; same Vite-based dev experience as ui/; trivial static deploy.
• Scope: keep v1 small (home, features, legal). Add blog or changelog via Astro content collections when needed.

Documentation (docs/)

Single Starlight site for all documentation in this repo — end-user guides, operator/self-host, and contributor material. Markdown is the source of truth; GitLab Pages publishes the built site (see Deployment).

• Generator: Starlight on Astro (same stack as www/; VitePress only if we later need heavy Vue-in-docs parity with ui/).
• Layout: Starlight project root is docs/ (package.json, astro.config.mjs, src/content/docs/). Top-level sidebar sections, for example:
  • Guides — using Garrison Bible Study, study workflows (grows over time).
  • Operator — install, self-host, upgrades.
  • Developer — contributing, repo layout, local dev; Planning nested here (docs/src/content/docs/developer/planning/).
• Planning: docs/src/content/docs/developer/planning/ (Developer → Planning in the sidebar). Relative links between planning pages stay as they are today.
• Hosting: GitLab Pages from CI on the default branch; artifact docs/dist/.
• URL: set Astro site and base in docs/astro.config.mjs for the GitLab Pages URL.
• Linking: www/ links to the docs site; ui/ may deep-link to help articles.

Mobile (mobile/)

• Kotlin Multiplatform with Compose Multiplatform for UI (may split to shared-logic-only if needed).
• v1 features: reminders, streaks, journal, distraction-free mode (subset of web).
• Push: habit reminders, messages, selected system announcements.
• Offline/sync: CRDT for journal/notes; SQLDelight local state; see Sync and Offline.
• Messaging (later): Apollo + WebSocket; standard message log per mentorship (Messaging).
• Apollo Kotlin for GraphQL; respect API minimum app version.

Integrations (technical)

• ChMS: deferred v1; design for PeopleProvider-style abstraction (Integrations).
• Logos: deep links from reference resolver (Bible and Scripture).

Deployment

See Deployment — Docker Compose self-host; managed SaaS on cloud provider TBD.