How sigveer/fullstack-v2026 works
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: pom.xml Shared Core · IkAlcoholApplication.kt Alcohol API · IkFoodApplication.kt Food API · docker-compose.yml Docker Compose
Components 25
Frontend
Vue SPA and UI composition
- Vue SPA · Vue 3 + Vite + TypeScript app
frontend/src/main.ts - App Shell · Router, views, composables, and reusable components
frontend/src/App.vue - API Boundary · Shared request/query layer used by composables
frontend/src/lib/api.ts
Backend
Shared core and two domain APIs
- Shared Core · Cross-cutting business and infrastructure module
backend/ik-common/pom.xml - Auth · JWT auth, security config, and user context
backend/ik-common/src/main/kotlin/com/iksystem/common/security/JwtService.kt - Identity · Organizations, memberships, users, and invitations
backend/ik-common/src/main/kotlin/com/iksystem/common/user/service/UserService.kt - Workflows · Checklists, documents, training, reports, and notifications
backend/ik-common/src/main/kotlin/com/iksystem/common/checklist/service/ChecklistService.kt - Shared Config · OpenAPI, email, S3, and global exception handling
backend/ik-common/src/main/kotlin/com/iksystem/common/config/SecurityConfig.kt - Food API · HACCP and food compliance service
backend/ik-food-service/src/main/kotlin/com/iksystem/food/IkFoodApplication.kt - HACCP Setup · Business setup wizard and checklist templates
backend/ik-food-service/src/main/kotlin/com/iksystem/food/haccpsetup/service/HaccpSetupService.kt - Temperature · Appliances, measurements, and monitoring
backend/ik-food-service/src/main/kotlin/com/iksystem/food/temperature/service/TemperatureService.kt - Food Deviations · Food deviation handling and status tracking
backend/ik-food-service/src/main/kotlin/com/iksystem/food/deviation/service/FoodDeviationService.kt - Food Dashboard · Operational overview for food compliance
backend/ik-food-service/src/main/kotlin/com/iksystem/food/dashboard/FoodDashboardService.kt - Alcohol API · Alcohol compliance service
backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/IkAlcoholApplication.kt - Age Verification · Shifts and verification workflow
backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/ageverification/service/AgeVerificationService.kt - Alcohol Policy · Policy management and rules
backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/alcoholpolicy/service/AlcoholPolicyService.kt - Alcohol Deviations · Deviation analysis and causal tracking
backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/deviation/service/AlcoholDeviationService.kt - Penalty Points · Penalty point tracking and handling
backend/ik-alcohol-service/src/main/kotlin/com/iksystem/alcohol/penaltypoints/service/PenaltyPointService.kt - Alcohol Dashboard · 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 · Local orchestration for the full stack
docker-compose.yml - Nginx · Serves the frontend container
frontend/nginx.conf - MySQL · Shared relational datastore
- Resend · Outbound email delivery integration
- S3 · File and document storage integration
Other components
- Browser · End-user entry point
Connections 29
- 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