jivanrij/go-no-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

this commit adds more documentation to the application

Browse Source
This commit is contained in:
Jonathan van Rij
2026-02-03 09:08:05 +01:00
parent 9441291070
commit 02dfc1568c
5 changed files with 488 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/technical-requirements.md
View File

@@ -13,7 +13,7 @@ ## 2. Tech Stack
- **Admin Panel:** Laravel Nova 5 at `/cp`
- **Database:** MySQL (`go-no-go`)
- **Auth (frontend):** Laravel Socialite with Azure AD SSO
- **Auth (Nova):** Laravel Fortify (email/password + 2FA)
- **Auth (Nova):** Built-in Nova authentication
- **Excel Export:** `maatwebsite/laravel-nova-excel`
## 3. Two Separate Interfaces
@@ -30,7 +30,7 @@ ### Authentication
Each interface has its own authentication method:
- **Frontend:** Azure AD Single Sign-On via Laravel Socialite. Users visit `/login`, get redirected to Azure AD, and are returned to `/auth/callback`. Socialite handles the OAuth flow. Users are created or matched by email on first login. No password stored for frontend users.
- **Nova:** Standard email/password login via Laravel Fortify with 2FA and email verification at `/cp/login`. Only administrators access Nova.
- **Nova:** Built-in Nova authentication at `/cp/login`. Already configured and working. Only administrators access Nova.
## 4. Frontend Architecture (Vue + Inertia.js v2)
@@ -149,6 +149,7 @@ ### sessions
| id | bigint unsigned | PK, auto-increment |
| user_id | bigint unsigned | FK to users.id, required |
| category_id | bigint unsigned | FK to categories.id, required |
| screening_id | bigint unsigned | FK to screenings.id, nullable |
| status | varchar(50) | required, enum: `in_progress`, `completed`, `abandoned` |
| score | integer | nullable, calculated from scored answers |
| result | varchar(50) | nullable, enum: `go`, `no_go`, `consult_leadership` |
@@ -187,6 +188,34 @@ ### answers
**Unique constraint:** `(session_id, question_id)` -- one answer per question per session.
### screenings
Pre-screening sessions. One per attempt. Tracks the 10 Yes/No pre-screening questions before category selection.
| Column | Type | Constraints |
|--------|------|-------------|
| id | bigint unsigned | PK, auto-increment |
| user_id | bigint unsigned | FK to users.id, required |
| score | integer | nullable, calculated from screening answers |
| passed | boolean | nullable, true if score >= 5 |
| created_at | timestamp | nullable |
| updated_at | timestamp | nullable |
### screening_answers
Stores answers to the 10 pre-screening questions.
| Column | Type | Constraints |
|--------|------|-------------|
| id | bigint unsigned | PK, auto-increment |
| screening_id | bigint unsigned | FK to screenings.id, required |
| question_number | unsigned integer | required, 1-10 |
| value | varchar(10) | required, `yes` or `no` |
| created_at | timestamp | nullable |
| updated_at | timestamp | nullable |
**Unique constraint:** `(screening_id, question_number)` -- one answer per question per screening.
### logs
Comprehensive activity log for usage analytics. Every meaningful user action is recorded to enable statistics on: who is using the application, which categories are used most, usage frequency, whether certain questions are always answered the same way, and whether specific firms or groups are more active than others.
@@ -209,6 +238,8 @@ #### Logged Actions
|--------|------|----------|
| `login` | User completes SSO | `{email, firm_name}` |
| `logout` | User logs out | — |
| `screening_started` | New screening created | — |
| `screening_completed` | Screening submitted | `{score, passed}` |
| `session_started` | New session created | `{category_id}` |
| `session_completed` | Session submitted | `{category_id, score, result}` |
| `session_abandoned` | Session marked abandoned | `{category_id}` |
@@ -221,12 +252,16 @@ ## 6. Frontend Routes & Controllers
| Method | Route | Controller | Vue Page | Description |
|--------|-------|------------|----------|-------------|
| GET | `/` | DashboardController@index | Dashboard | Start page. Start new session or view past sessions. |
| GET | `/` | LandingController@index | Landing | Landing page. Describes the application. Has a "Continue" button. |
| GET | `/login` | SocialiteController@redirect | — | Redirects to Azure AD for SSO |
| GET | `/auth/callback` | SocialiteController@callback | — | Azure AD callback, creates/finds user, logs in |
| POST | `/logout` | SocialiteController@logout | — | Logout |
| POST | `/sessions` | SessionController@store | — | Create a new session for a selected category |
| GET | `/sessions/{session}` | SessionController@show | Session/Show | Basic info form + questionnaire flow |
| POST | `/screening` | ScreeningController@store | — | Create a new screening session |
| GET | `/screening/{screening}` | ScreeningController@show | Screening/Show | Pre-screening Yes/No questions (10 questions) |
| PUT | `/screening/{screening}` | ScreeningController@update | — | Save screening answers |
| GET | `/screening/{screening}/result` | ScreeningController@result | Screening/Result | Pre-screening result (pass/fail). If pass, shows category picker. |
| POST | `/sessions` | SessionController@store | — | Create a new session for a selected category (from screening result page) |
| GET | `/sessions/{session}` | SessionController@show | Session/Show | Basic info form + category questionnaire flow |
| PUT | `/sessions/{session}` | SessionController@update | — | Save answers, update basic info, submit session |
| GET | `/sessions/{session}/result` | SessionController@result | Session/Result | View final result after submission |
@@ -235,22 +270,37 @@ ## 6. Frontend Routes & Controllers
## 7. Questionnaire Flow
1. User logs in via Azure AD SSO
2. `/` is the start page — shows: start new session, view past sessions
3. User selects a category to start a new session
4. Basic Information form (client name, client contact, lead firm name, lead firm contact)
5. Step through question groups in order (each group is a page/step)
6. Each question renders based on its field configuration:
2. `/` is the landing page — describes the application purpose, has a "Continue" button
3. User clicks Continue → creates a screening session, redirected to pre-screening questions
4. Pre-screening: 10 Yes/No scored questions (1 point per Yes)
5. Pre-screening result:
- Score < 5 points → No Go result page (red). "Again" button returns to `/`.
- Score >= 5 points → pass. Page shows category picker to continue.
6. User selects a category → creates a session, redirected to Session/Show
7. Basic Information form (client name, client contact, lead firm name, lead firm contact)
8. Step through question groups in order (each group is a page/step)
9. Each question renders based on its field configuration:
- If `has_yes`/`has_no`/`has_na` are all false → render as open text (textarea only)
- If any are true → render radio buttons for the enabled options
- If `details` is set → render a details textarea with the appropriate requirement behavior (`required`, `optional`, `req_on_yes`, `req_on_no`)
7. Running score displayed (for scored questions only)
8. Color-coded result indicator updates live (green/yellow/red)
9. Final step: Additional comments free text
10. Submit and view result (GO / NO GO / Consult Leadership)
11. Session saved with score and result
10. Running score displayed (for scored questions only)
11. Color-coded result indicator updates live (green/yellow/red)
12. Final step: Additional comments free text
13. Submit and view result (GO / NO GO / Consult Leadership)
14. Session saved with score and result
15. All result pages have an "Again" button that returns to `/`
## 8. Scoring Logic
### Pre-Screening Threshold
The pre-screening uses a simple pass/fail:
- 10 Yes/No questions, each Yes = 1 point
- Score >= 5 → pass (proceed to category selection)
- Score < 5 → fail (No Go, return to start)
### Category Questionnaire Scoring
- Only questions with `is_scored = true` are scored
- **Yes** = 1 point
- **No** = 0 points
@@ -274,6 +324,7 @@ ## 9. Nova Resources & Policies
| CategoryResource | Category | CategoryPolicy | No | Lookup data only — no dedicated resource page. Exists as a Nova resource class so it can be referenced in relational fields (BelongsTo, HasMany). No CRUD operations exposed. |
| QuestionGroupResource | QuestionGroup | QuestionGroupPolicy | No | Read-only. Filterable by category. No create, update, or delete. Displayed inline via HasMany on other resources only. |
| QuestionResource | Question | QuestionPolicy | Yes | Only the `text` field is editable by administrators. All other fields (has_yes, has_no, has_na, details, is_scored, sort_order) are read-only after seeding. No create or delete. |
| ScreeningResource | Screening | ScreeningPolicy | Yes | Read-only. Filterable by user and result. View pre-screening scores. No create, update, or delete from Nova. |
| SessionResource | Session | SessionPolicy | Yes | Filterable by user, category, and status. View scores and results. No create, update, or delete from Nova. |
| AnswerResource | Answer | AnswerPolicy | No | Strictly read-only — no create, update, or delete by anyone (administrators included). Viewed within session context only. |
| LogResource | Log | LogPolicy | Yes | Read-only. Filterable by user, category, action, and date range. For usage analytics and statistics. No create, update, or delete. |
@@ -285,6 +336,7 @@ ### Policy Summary
| Category | Yes | No | No | No |
| QuestionGroup | Yes | No | No | No |
| Question | Yes | No | Yes (text only) | No |
| Screening | Yes | No | No | No |
| Session | Yes | No | No | No |
| Answer | Yes | No | No | No |
| Log | Yes | No | No | No |