# sigveer/fullstack-v2026 architecture

> Architecture diagram of the GitHub repository sigveer/fullstack-v2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sigveer/fullstack-v2026
- Repository: https://github.com/sigveer/fullstack-v2026

## Overview

1. **Top-level shape**
   - This repo is a three-part fullstack system: a Vue 3 frontend, and two Spring Boot/Kotlin backend services, one for **food** and one for **alcohol** compliance.
   - All services are containerized and orchestrated with Docker Compose. The frontend is served through Nginx, while the backends expose separate HTTP APIs on different ports.

2. **Backend service boundaries**
   - The backend is split into Maven modules:
     - **ik-common**: shared business capabilities and infrastructure
     - **ik-food-service**: food/HACCP domain
     - **ik-alcohol-service**: alcohol compliance domain
   - The common module is the largest and acts like a shared application core, while the food and alcohol services add domain-specific endpoints and models.

3. **Shared backend core**
   - `ik-common` contains the cross-cutting business areas used across the product:
     - authentication and JWT/security
     - organizations and memberships
     - users and invitations
     - documents and file-related workflows
     - checklists and checklist completions
     - training logs
     - reports and PDF generation
     - notifications and scheduled reminders
   - It also contains global exception handling and shared configuration such as OpenAPI, security, email, and S3-related config.

4. **Food domain service**
   - `ik-food-service` focuses on restaurant/HACCP functionality:
     - HACCP setup wizard support
     - temperature appliances and measurements
     - food deviations and their statuses/types
     - a food dashboard for operational overview
   - Its code is organized in the same controller/service/repository pattern as the common module, but limited to food-specific use cases.

5. **Alcohol domain service**
   - `ik-alcohol-service` handles alcohol-specific compliance:
     - age verification shifts
     - alcohol policy management
     - alcohol deviations and causal analysis
     - penalty points
     - an alcohol dashboard
   - Like the food service, it is a separate API boundary with its own Spring Boot entry point and persistence layer.

6. **Request and data flow on the backend**
   - The backend follows a standard layered flow:
     - REST controller receives request
     - service layer applies business rules
     - repository layer persists/queries data
     - MySQL stores the records
   - DTO files are used heavily, so API payloads are separated from persistence entities/models.

7. **Persistence and schema management**
   - All backend data is backed by MySQL and managed with Flyway migrations.
   - The common module includes the migration history and seed data, including schema additions for checklists, deviations, training, documents, notifications, invitations, reports, and age verification.
   - This suggests one shared database schema supporting both domain services rather than isolated databases per service.

8. **Security and authentication**
   - Security is centered on JWT-based authentication in the common module.
   - Key components include JWT services, a JWT auth filter, an authenticated-user abstraction, and a Spring Security config.
   - Authentication and user/account management are shared concerns, not duplicated in the domain services.

9. **Background jobs and external integrations**
   - Notifications include schedulers for recurring or deadline-based reminders, such as checklist, training, and beverage/license expiry-related jobs.
   - External integrations are implied by config and supporting classes:
     - **Resend** for email delivery
     - **S3** for object/file storage
     - **OpenAPI/Swagger** for API documentation
   - Reports also have a PDF generator and HTML template, indicating server-side report rendering.

10. **Frontend architecture**
   - The frontend is a Vue 3 + Vite + TypeScript single-page app.
   - It is organized by feature area:
     - views for each screen
     - composables for API/state logic
     - Pinia-like stores for shared app state
     - reusable UI components and feature components
   - The UI is built from many small, composable components rather than large page monoliths.

11. **Frontend-to-backend interaction**
   - Frontend composables like `useAuth`, `useChecklists`, `useTemperatureMonitoring`, `useAlcoholPolicy`, and `useReports` encapsulate API calls and local state.
   - `frontend/src/lib/api.ts` and `query.ts` are the likely HTTP/data-access boundary.
   - Views consume these composables and render domain cards, dialogs, tables, and wizards.

12. **Product-level user journeys**
   - The main workflows visible in the repo are:
     - login and organization setup
     - HACCP/business setup wizard
     - checklist creation and completion
     - temperature monitoring
     - food/alcohol deviation reporting and follow-up
     - training tracking
     - age verification and penalty handling
     - dashboards and reports
   - The frontend routes map directly to these business areas, which mirrors the backend module split.

13. **Testing and delivery**
   - Each backend module has a parallel test suite for controllers and services.
   - The frontend has component tests alongside feature components, showing the UI is tested at the component level.
   - CI is present via GitHub Actions, and the whole stack is designed to run locally through Docker Compose or separately in dev mode.

14. **Diagram guidance**
   - A good architecture diagram should show:
     - one browser/client tier
     - one Vue SPA frontend container
     - two backend API services
     - one shared MySQL database
     - shared infrastructure concerns inside the common backend module
     - external integrations for email, file storage, and API documentation
   - The most important boundary is between **shared core capabilities** and the two **domain-specific compliance services**.

Main entry points: [`backend/ik-common/pom.xml`](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/pom.xml) (Shared Core), [`backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/IkAlcoholApplication.kt`](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/IkAlcoholApplication.kt) (Alcohol API), [`backend/ik-food-service/src/main/kotlin/com/iksystem/food/IkFoodApplication.kt`](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/IkFoodApplication.kt) (Food API), [`docker-compose.yml`](https://github.com/sigveer/fullstack-v2026/blob/main/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa["Vue SPA<br/>frontend app<br/>[main.ts]"]
  node_ui["App Shell<br/>frontend shell<br/>[App.vue]"]
  node_api["API Boundary<br/>http client<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_common["Shared Core<br/>spring module<br/>[pom.xml]"]
  node_auth["Auth<br/>security<br/>[JwtService.kt]"]
  node_orgs["Identity<br/>core domain<br/>[UserService.kt]"]
  node_workflows["Workflows<br/>operations"]
  node_sharedcfg["Shared Config<br/>[SecurityConfig.kt]"]
  node_food["Food API<br/>spring service"]
  node_haccp["HACCP Setup<br/>food feature"]
  node_temp["Temperature<br/>food feature"]
  node_fooddev["Food Deviations<br/>food feature"]
  node_fooddash["Food Dashboard<br/>food feature"]
  node_alcohol["Alcohol API<br/>spring service"]
  node_agev["Age Verification<br/>alcohol feature"]
  node_policy["Alcohol Policy<br/>alcohol feature"]
  node_aldev["Alcohol Deviations<br/>alcohol feature"]
  node_penalty["Penalty Points<br/>alcohol feature"]
  node_alcdash["Alcohol Dashboard<br/>alcohol feature"]
end

subgraph group_infra["Runtime"]
  node_compose["Docker Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_nginx["Nginx<br/>web server<br/>[nginx.conf]"]
  node_mysql[("MySQL<br/>database")]
  node_resend["Resend<br/>email service"]
  node_s3[("S3<br/>object storage")]
end

node_browser(("Browser<br/>client"))

node_browser -->|"uses"| node_spa
node_spa -->|"renders"| node_ui
node_ui -->|"calls"| node_api
node_api -->|"shared APIs"| node_common
node_api -->|"food APIs"| node_food
node_api -->|"alcohol APIs"| node_alcohol
node_common -->|"secures"| node_auth
node_common -->|"manages"| node_orgs
node_common -->|"coordinates"| node_workflows
node_common -->|"configures"| node_sharedcfg
node_food -->|"implements"| node_haccp
node_food -->|"implements"| node_temp
node_food -->|"implements"| node_fooddev
node_food -->|"implements"| node_fooddash
node_alcohol -->|"implements"| node_agev
node_alcohol -->|"implements"| node_policy
node_alcohol -->|"implements"| node_aldev
node_alcohol -->|"implements"| node_penalty
node_alcohol -->|"implements"| node_alcdash
node_common -->|"persists"| node_mysql
node_food -->|"persists"| node_mysql
node_alcohol -->|"persists"| node_mysql
node_common -->|"emails"| node_resend
node_common -->|"files"| node_s3
node_compose -->|"runs"| node_nginx
node_compose -->|"runs"| node_food
node_compose -->|"runs"| node_alcohol
node_compose -->|"builds"| node_common
node_nginx -->|"serves"| node_spa

click node_spa "https://github.com/sigveer/fullstack-v2026/blob/main/frontend/src/main.ts"
click node_ui "https://github.com/sigveer/fullstack-v2026/blob/main/frontend/src/App.vue"
click node_api "https://github.com/sigveer/fullstack-v2026/blob/main/frontend/src/lib/api.ts"
click node_common "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/pom.xml"
click node_auth "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/security/JwtService.kt"
click node_orgs "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/user/service/UserService.kt"
click node_workflows "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/checklist/service/ChecklistService.kt"
click node_sharedcfg "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/config/SecurityConfig.kt"
click node_food "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/IkFoodApplication.kt"
click node_haccp "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/haccpsetup/service/HaccpSetupService.kt"
click node_temp "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/temperature/service/TemperatureService.kt"
click node_fooddev "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/deviation/service/FoodDeviationService.kt"
click node_fooddash "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/dashboard/FoodDashboardService.kt"
click node_alcohol "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/IkAlcoholApplication.kt"
click node_agev "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/ageverification/service/AgeVerificationService.kt"
click node_policy "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/alcoholpolicy/service/AlcoholPolicyService.kt"
click node_aldev "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/deviation/service/AlcoholDeviationService.kt"
click node_penalty "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/penaltypoints/service/PenaltyPointService.kt"
click node_alcdash "https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/dashboard/AlcoholDashboardService.kt"
click node_compose "https://github.com/sigveer/fullstack-v2026/blob/main/docker-compose.yml"
click node_nginx "https://github.com/sigveer/fullstack-v2026/blob/main/frontend/nginx.conf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_ui,node_api toneBlue
class node_common,node_auth,node_orgs,node_workflows,node_sharedcfg,node_food,node_haccp,node_temp,node_fooddev,node_fooddash,node_alcohol,node_agev,node_policy,node_aldev,node_penalty,node_alcdash toneAmber
class node_compose,node_nginx,node_mysql,node_resend,node_s3 toneMint
class node_browser toneNeutral
```

## Components

### Frontend

Vue SPA and UI composition

- [Vue SPA](https://github.com/sigveer/fullstack-v2026/blob/main/frontend/src/main.ts): frontend app · Vue 3 + Vite + TypeScript app · `frontend/src/main.ts`
- [App Shell](https://github.com/sigveer/fullstack-v2026/blob/main/frontend/src/App.vue): frontend shell · Router, views, composables, and reusable components · `frontend/src/App.vue`
- [API Boundary](https://github.com/sigveer/fullstack-v2026/blob/main/frontend/src/lib/api.ts): http client · Shared request/query layer used by composables · `frontend/src/lib/api.ts`

### Backend

Shared core and two domain APIs

- [Shared Core](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/pom.xml): spring module · Cross-cutting business and infrastructure module · `backend/ik-common/pom.xml`
- [Auth](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/security/JwtService.kt): security · JWT auth, security config, and user context · `backend/ik-common/src/main/kotlin/com/iksystem/common/security/JwtService.kt`
- [Identity](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/user/service/UserService.kt): core domain · Organizations, memberships, users, and invitations · `backend/ik-common/src/main/kotlin/com/iksystem/common/user/service/UserService.kt`
- [Workflows](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/checklist/service/ChecklistService.kt): operations · Checklists, documents, training, reports, and notifications · `backend/ik-common/src/main/kotlin/com/iksystem/common/checklist/service/ChecklistService.kt`
- [Shared Config](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-common/src/main/kotlin/com/iksystem/common/config/SecurityConfig.kt): config · OpenAPI, email, S3, and global exception handling · `backend/ik-common/src/main/kotlin/com/iksystem/common/config/SecurityConfig.kt`
- [Food API](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/IkFoodApplication.kt): spring service · HACCP and food compliance service · `backend/ik-food-service/src/main/kotlin/com/iksystem/food/IkFoodApplication.kt`
- [HACCP Setup](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/haccpsetup/service/HaccpSetupService.kt): food feature · Business setup wizard and checklist templates · `backend/ik-food-service/src/main/kotlin/com/iksystem/food/haccpsetup/service/HaccpSetupService.kt`
- [Temperature](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/temperature/service/TemperatureService.kt): food feature · Appliances, measurements, and monitoring · `backend/ik-food-service/src/main/kotlin/com/iksystem/food/temperature/service/TemperatureService.kt`
- [Food Deviations](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/deviation/service/FoodDeviationService.kt): food feature · Food deviation handling and status tracking · `backend/ik-food-service/src/main/kotlin/com/iksystem/food/deviation/service/FoodDeviationService.kt`
- [Food Dashboard](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-food-service/src/main/kotlin/com/iksystem/food/dashboard/FoodDashboardService.kt): food feature · Operational overview for food compliance · `backend/ik-food-service/src/main/kotlin/com/iksystem/food/dashboard/FoodDashboardService.kt`
- [Alcohol API](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/IkAlcoholApplication.kt): spring service · Alcohol compliance service · `backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/IkAlcoholApplication.kt`
- [Age Verification](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/ageverification/service/AgeVerificationService.kt): alcohol feature · Shifts and verification workflow · `backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/ageverification/service/AgeVerificationService.kt`
- [Alcohol Policy](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/alcoholpolicy/service/AlcoholPolicyService.kt): alcohol feature · Policy management and rules · `backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/alcoholpolicy/service/AlcoholPolicyService.kt`
- [Alcohol Deviations](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/deviation/service/AlcoholDeviationService.kt): alcohol feature · Deviation analysis and causal tracking · `backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/deviation/service/AlcoholDeviationService.kt`
- [Penalty Points](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/penaltypoints/service/PenaltyPointService.kt): alcohol feature · Penalty point tracking and handling · `backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/penaltypoints/service/PenaltyPointService.kt`
- [Alcohol Dashboard](https://github.com/sigveer/fullstack-v2026/blob/main/backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/dashboard/AlcoholDashboardService.kt): alcohol feature · Operational overview for alcohol compliance · `backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/dashboard/AlcoholDashboardService.kt`

### Runtime

Containerization and external services

- [Docker Compose](https://github.com/sigveer/fullstack-v2026/blob/main/docker-compose.yml): deployment · Local orchestration for the full stack · `docker-compose.yml`
- [Nginx](https://github.com/sigveer/fullstack-v2026/blob/main/frontend/nginx.conf): web server · Serves the frontend container · `frontend/nginx.conf`
- **MySQL**: database · Shared relational datastore
- **Resend**: email service · Outbound email delivery integration
- **S3**: object storage · File and document storage integration

### Other components

- **Browser**: client · End-user entry point

## Connections

- Browser → Vue SPA: uses · Browser loads the SPA
- Vue SPA → App Shell: renders · App delegates to views, components, and router
- App Shell → API Boundary: calls · Feature composables use the HTTP boundary
- API Boundary → Shared Core: shared APIs · Shared product capabilities exposed through APIs
- API Boundary → Food API: food APIs · Frontend feature calls into food service endpoints
- API Boundary → Alcohol API: alcohol APIs · Frontend feature calls into alcohol service endpoints
- Shared Core → Auth: secures · JWT and security concerns
- Shared Core → Identity: manages · Users, organizations, memberships, invitations
- Shared Core → Workflows: coordinates · Checklists, documents, training, reports, notifications
- Shared Core → Shared Config: configures · OpenAPI, Resend, S3, and exception handling
- Food API → HACCP Setup: implements · Wizard and template generation
- Food API → Temperature: implements · Temperature tracking
- Food API → Food Deviations: implements · Food deviations
- Food API → Food Dashboard: implements · Food dashboard
- Alcohol API → Age Verification: implements · Age verification shifts
- Alcohol API → Alcohol Policy: implements · Policy management
- Alcohol API → Alcohol Deviations: implements · Alcohol deviations and analysis
- Alcohol API → Penalty Points: implements · Penalty points
- Alcohol API → Alcohol Dashboard: implements · Alcohol dashboard
- Shared Core → MySQL: persists · Shared schema stored in MySQL
- Food API → MySQL: persists · Food domain data stored in MySQL
- Alcohol API → MySQL: persists · Alcohol domain data stored in MySQL
- Shared Core → Resend: emails · Notification delivery
- Shared Core → S3: files · Document and asset storage
- Docker Compose → Nginx: runs · Containerized frontend delivery
- Docker Compose → Food API: runs · Starts food API container
- Docker Compose → Alcohol API: runs · Starts alcohol API container
- Docker Compose → Shared Core: builds · Shared backend module included in backend image
- Nginx → Vue SPA: serves · Frontend static assets and SPA entry
