Engineering record
Platform architecture
The eleven architecture artefacts requested in the brief, plus a frank statement of what this build does and does not yet run.
Read this first
Scope of this build
Implemented and reviewable here
The full public information architecture, the directory and filter interactions, detail templates, comparison, shortlists, the assessment and predictor tools, the forms with real validation behaviour, and the three portal interfaces.
Specified but not runnable in a static preview
Authentication, the database, the CRM write paths, document storage, payments, notifications and the AI assistant's retrieval. Those are specified in the tables below and are built on the application stack at implementation time.
Information architecture
1. Sitemap
Public website — 22 areas
HomeAboutStudy in IndiaStudy AbroadCollegesUniversitiesCoursesEntrance ExamsScholarshipsCareer GuidanceCollege PredictorCourse FinderUniversity FinderCollege CompareCollege ReviewsStudent Q&AArticlesEducation NewsEventsContactFree CounsellingApply Now
Student portal — 18 areas
Student LoginStudent RegistrationStudent DashboardProfileShortlisted CollegesShortlisted UniversitiesSaved CoursesCompareMy ApplicationsMy DocumentsMy CounsellingAppointmentsPaymentsNotificationsMessagesScholarshipsCareer AssessmentAI Career Assistant
Counsellor portal — 10 areas
Counsellor DashboardAssigned LeadsStudent ProfilesFollow-upsCounselling CalendarApplicationsDocumentsNotesTasksStudent Communication
Admin portal — 25 areas
Admin DashboardStudentsLeadsCounsellorsCollegesUniversitiesCoursesExamsScholarshipsCountriesApplicationsDocumentsReviewsQ&AArticlesNewsEventsTestimonialsBannersPaymentsNotificationsSEO ManagerAnalyticsSettingsRoles & Permissions
3 journeys
2. User journey map
| Stage | Student intent | What the platform does | Lead/CRM event |
|---|---|---|---|
| Discovery | Understand what is possible | Home, destination and course pages with plain-language explainers | Session, no lead |
| Research | Compare options on facts | Directory filters, detail templates, comparison table | search, college_view, compare |
| Evaluate fit | Test whether I qualify | Career Compass, college predictor with explicit bands | assessment_completed |
| Contact | Ask a person | Free counselling form, WhatsApp, callback | lead_created, lead_scored |
| Counselling | Get a plan | Appointment booking, counsellor notes, shortlist shared | appointment_booked |
| Application | Submit correctly | Document checklist, upload, review, stage tracking | application_started |
| Submission | Be filed on time | Deadline reminders, status log per change | application_submitted |
| Offer and visa | Convert the offer | Deposit and visa stage tracking, document verification | offer_received, visa_stage |
| Enrolment | Arrive prepared | Pre-departure checklist, notifications | enrolled |
Operations
3. Admin and counsellor journey map
| Stage | Actor | Platform surface | Control |
|---|---|---|---|
| Inbound | System | Lead created from web, WhatsApp, event, referral or walk-in | Source is recorded, never guessed |
| Routing | Admin | Lead assignment by destination and capacity | Round-robin with manual override |
| First contact | Counsellor | Assigned leads list with next follow-up | Follow-up reminders and snooze |
| Qualification | Counsellor | Lead score, notes, call outcome | Stage transition requires a note |
| Counselling | Counsellor | Calendar with day/week/month views | Counsellor blocks unavailable time |
| Application | Counsellor | Application stage update with audit log | Every change writes actor, time, from-state, to-state |
| Documents | Counsellor | Review queue with approve or re-upload | Identity documents are view-only after verification |
| Reporting | Admin | Funnel, counsellor performance, destination mix | Metrics are computed, not entered |
PostgreSQL
4. Database entity relationship diagram
Core entities shown. Catalogue entities (Colleges, Universities, Campuses, Countries, States, Cities, Courses, CourseSpecializations, CollegeCourses, UniversityCourses, Exams, ExamDates, ExamCutoffs, Scholarships, Reviews, Questions, Answers, Articles, News, Events, Testimonials, Messages, SEORecords, Banners, FAQs) follow the same pattern: a primary key, foreign keys to the parent catalogue entity, a provenance block, and a soft-delete flag.
Data layer
Index and integrity plan
| Concern | Implementation |
|---|---|
| Full-text search | Generated tsvector column on catalogue tables with a GIN index; PostgreSQL first, OpenSearch only when scale requires it |
| Pagination | Keyset pagination on (sort_key, id) to avoid deep-offset cost |
| N+1 prevention | Relation loaders on list endpoints; the card payload is one query |
| Referential integrity | Foreign keys with ON DELETE RESTRICT for catalogue parents, ON DELETE CASCADE for child rows only |
| Audit | Append-only AuditLogs table; no UPDATE or DELETE grant for application roles |
| Provenance | Every volatile column is paired with source and verified_at, so the UI can render the stamp |
| Soft delete | deleted_at on catalogue tables so published URLs survive an unpublish action |
Contract
5. API architecture
| Group | Endpoints | Auth | Notes |
|---|---|---|---|
| Catalogue (read) | GET /colleges, /colleges/{slug}, /universities, /courses, /exams, /scholarships, /countries | Public | Cacheable, filter parameters validated against an allow-list, provenance fields always returned |
| Search | GET /search?q=&type=&page= | Public | Full-text with trigram fallback for typo tolerance; server-side pagination only |
| Compare | POST /compare | Public | Body carries 2-4 entity refs; the server returns the attribute matrix and per-row provenance |
| Tools | POST /predictor/run, POST /assessment/submit | Public (rate limited) | Modular per-exam predictors; the response always includes the uncertainty band |
| Leads | POST /leads, PATCH /leads/{id}, POST /leads/{id}/activities | Public create, staff update | Creation is idempotent against a submission token; every mutation writes an activity row |
| Auth | POST /auth/register, /auth/login, /auth/otp/request, /auth/otp/verify, /auth/logout | Session | Argon2id hashing, rotating sessions, CSRF token on state-changing routes from cookie sessions |
| Student | GET/PATCH /me, /me/shortlist, /me/applications, /me/documents, /me/appointments | Student | Ownership enforced in the query, not the controller |
| Staff | GET /staff/leads, PATCH /staff/applications/{id}/stage, POST /staff/documents/{id}/review | Counsellor | Scope-limited query builders per role |
| Admin | CRUD /admin/{catalogue}, POST /admin/import, GET /admin/analytics | Admin | Every write writes an audit row; imports validate before commit |
| AI | POST /ai/assistant/message | Public (rate limited) | Retrieval over the verified catalogue only; responses carry citations and refuse to answer outside the dataset |
Reuse
6. Component architecture
Shared UI components
CollegeCardUniversityCardCourseCardExamCardScholarshipCardArticleCardReviewCardEventCardSearchFiltersCompareTableShortlistButtonApplyButtonCounsellingCTADashboardCardApplicationTimelineDocumentUploaderNotificationPanelProvenanceFieldEmptyStateSkeletonBlockErrorSummaryToast
Layout and structure
SiteHeaderMainNavUtilityBarMobileActionBarFloatingActionsSiteFooterPageHeadStickySubNavSidebarLayoutDashLayoutDrawerShellAIThread
Cards are data-driven: the same CollegeCard renders in the directory, in related rails, in the shortlist and in comparison. ProvenanceField is the single component that decides how a verified, sample or unverified value is rendered, so no page can accidentally present an unverified number as fact.
Identity
7. Authentication architecture
| Layer | Decision | Reason |
|---|---|---|
| Primary credential | Email or mobile plus password | Both are already collected as lead fields |
| Second route | One-time code over SMS | Accessibility: WCAG 2.2 requires an alternative to memorisation |
| Optional | Google OAuth | Reduces friction for student accounts, never the only route |
| Password storage | Argon2id with per-user salt and a tuned cost parameter | Current recommended practice for password hashing |
| Session | Server-side session with a rotating opaque token in a Secure, HttpOnly, SameSite=Lax cookie | Revocable, unlike a stateless token |
| CSRF | Double-submit token on every state-changing request from a cookie session | Cookie sessions need it; bearer-token APIs do not |
| Elevation | Second factor required for Admin and Super Admin | Privileged accounts hold the widest data access |
| Rate limiting | Per-IP and per-account limits on login, OTP and public form endpoints | Credential stuffing and lead-spam defence |
| Recovery | Single-use, time-boxed reset token delivered to the verified channel | No security questions |
Role-based access control
8. Permission matrix
Permission is enforced in the data-access layer, not the interface. Hiding a button is a convenience, never the control.
| Capability | Super Admin | Admin | Counsellor | Content Manager | Student |
|---|---|---|---|---|---|
| Manage roles and permissions | Full | No | No | No | No |
| Manage staff accounts | Full | Create and edit | No | No | No |
| Catalogue create and edit | Full | Full | Read | Editorial fields only | Public read |
| Publish and unpublish | Full | Full | No | Own content | No |
| View any student record | Full | Full | Assigned only | No | Self only |
| Change application stage | Full | Full | Assigned only | No | No |
| Review documents | Full | Full | Assigned only | No | Upload own |
| Manage leads and assignment | Full | Full | Assigned only | No | Own enquiries |
| Moderate reviews and Q&A | Full | Full | Answer | Moderate | Submit and report |
| View payments and invoices | Full | Read | No | No | Own invoices |
| Import datasets | Full | Full | No | No | No |
| Read audit log | Full | Read | Own actions | Own actions | No |
Discoverability
9. SEO architecture
| Element | Implementation |
|---|---|
| Rendering | Server-rendered catalogue and detail pages so crawlers receive complete content; client hydration only for interactive filtering |
| URL pattern | /colleges/{slug}, /courses/{slug}, /exams/{slug}, /scholarships/{slug}, /study-in-{country}, /articles/{slug} |
| Canonical | Absolute canonical on every page; filtered directory views canonicalise to the base path with parameters excluded from the index |
| Title and description | Template per entity type with the differentiator first, held inside length limits |
| Sitemap | Generated sitemap index split by entity type, with lastmod driven by the record's own updated_at |
| Robots | Disallow on portal routes and preview routes; the sitemap reference at the root |
| Structured data | EducationalOrganization and WebSite sitewide; Course, Article, FAQPage and BreadcrumbList where the page genuinely carries that content |
| Review markup | Emitted only when the page publishes real, moderated reviews — never on aggregate claims |
| Internal linking | Related courses, related institutions, exam-to-course and course-to-institution links generated from the join tables |
| Pagination | Rel next and prev plus self-canonical per page |
| Speed | Static generation for catalogue pages, responsive images with intrinsic dimensions, lazy loading below the fold, code splitting per route |
| Local SEO | LocalBusiness markup added only after the client confirms the address, phone and hours |
Runtime
10. Deployment architecture
| Layer | Choice | Notes |
|---|---|---|
| Framework | Next.js with TypeScript | Server rendering for the catalogue, static generation where data changes rarely |
| UI layer | Tailwind CSS over an accessible component primitives base | Token-driven, so the brand palette resolves from one place |
| Database | PostgreSQL | Relational integrity for the catalogue, the funnel and the audit trail |
| ORM | Prisma with explicit migrations | Typed queries and a reviewable migration history |
| Object storage | S3-compatible private bucket for documents | Objects reachable only through short-lived signed URLs; no public read |
| Search | PostgreSQL full-text first | OpenSearch only when the catalogue outgrows it; the query interface stays the same |
| Cache and CDN | Edge cache in front of catalogue pages, purge on publish | Filtered views bypass the cache |
| Background work | Queue for notifications, imports and document scanning | Never inline in a request |
| Observability | Structured request logs, error tracking, and the audit table for state changes | No personal data in log payloads |
| Environments | Preview, staging, production with separate credentials | Preview data is never production data |
| This preview | Static hosted output | HTML, CSS and JavaScript only — no server process, so nothing that requires a runtime is faked |
Delivery order
11. Feature priority list
| Priority | Scope | Contents |
|---|---|---|
| P0 — launch critical | The platform must not go live without these | Homepage, India colleges and universities, courses, study-abroad destinations, abroad universities, search, filters, college, university and course detail pages, compare, shortlist, counselling form, student registration and login, student dashboard, lead CRM, counsellor dashboard, admin CMS, applications, document upload, notifications, articles, SEO foundations, WhatsApp entry point, AI assistant with grounded retrieval |
| P1 — important, shortly after launch | Adds depth without blocking the launch | College predictor for the top exams, career assessment, reviews and Q&A modules, events, payments, CSV import, analytics dashboards, SEO manager, counsellor calendar with time-blocking |
| P2 — expansion | Built once the core is stable and the data is verified | Mobile app, push notifications, recommendation engine, SOP and document AI assistants, video counselling, partner portal, subscriptions, affiliate tracking, multi-city offices, multi-language, marketing automation, CRM integrations |
Editorial control
Data accuracy rules encoded in the platform
Never fabricated
- Rankings and accreditations
- Fees and scholarship amounts
- Placement and salary figures
- Admission and exam deadlines
- Visa and immigration rules
- Local-business details
How the platform enforces it
- Volatile columns are paired with source and verified_at
- A single ProvenanceField component renders every value
- A missing value renders the required notice, never an estimate
- The AI assistant answers only from verified rows and cites them
- Citation of unverified data is refused at the retrieval layer
Next step
Ready for the implementation phase
This build establishes the information architecture, the design system and the interaction model. The application stack work starts from here.