Documentation
A product surface should explain its own boundaries.
Architecture, data responsibilities, API routes and implementation status for the Gritnox concept, written for reviewers who need to distinguish demonstrated behavior from production claims.
Next.js surface
Public discovery, sourcing and documentation routes
Django API
Catalog, procurement, accounts, sellers, orders and administration
MongoDB
Catalog records, RFQs, inquiries and marketplace data
Disclosure layer
Evidence states and demo boundaries in the interface
01 · System
Architecture at a glance
The browser renders the Next.js App Router interface. Public catalog and procurement requests reach the Django REST API, which reads or writes MongoDB. Authenticated marketplace functions use an HttpOnly Django session with CSRF-protected writes. The public catalog remains independent of checkout.
- The public catalog, part detail, equipment and supplier views use unauthenticated read APIs.
- RFQ and contact submissions are public, validated and rate-limited at the API boundary.
- Protected dashboard and seller operations rely on API-side authorization, not client route guards alone.
- Demo data is identified in the interface and should not be treated as live market data.
02 · Surface
Public routes
Search and faceted part discovery
Part identity, evidence, cross-references and offers
Equipment directory and fitment counts
Illustrative supplier directory
Sourcing list and demo RFQ submission
Product thesis, data policy and status
Workflow guidance and troubleshooting
Evidence, data labeling and safety boundaries
Data categories, session cookies and browser storage
Demo-use and commercial boundaries
Target standard and known gaps
Validated public inquiry intake
Implemented release history
Live visual specifications
This implementation map
03 · Contract
Gritnox API surface
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /auth/csrf/ | CSRF bootstrap for session-authenticated requests |
| POST | /auth/login/ | Throttled session login with generic failures |
| POST | /auth/register/ | Buyer registration with session and verification mail |
| POST | /auth/logout/ | CSRF-protected session sign-out |
| POST | /auth/password/change/ | Current-password check and account-wide session revocation |
| POST | /auth/password-reset/request/ | Generic account recovery request |
| POST | /auth/email/verify/confirm/ | Signed, time-limited email verification |
| GET | /dashboard/admin/overview/ | Administrator operating aggregates |
| GET | /dashboard/buyer/overview/ | Buyer order and spend aggregates |
| GET | /seller-analytics/ | Seller sales, order and wallet analytics |
| GET | /catalog/categories/ | Categories with published part counts |
| GET | /catalog/manufacturers/ | Manufacturers and catalog presence |
| GET | /catalog/parts/ | Search, filters, ordering and pagination |
| GET | /catalog/parts/{slug}/ | Part identity, identifiers, fitment and offers |
| GET | /catalog/equipment/ | Equipment models and fitment records |
| GET | /catalog/suppliers/ | Illustrative supplier profiles |
| GET | /catalog/stats/ | Catalog demonstration totals |
| POST | /procurement/rfqs/ | Validated demo RFQ submission |
| POST | /support/contact/ | Validated public contact intake |
Part search accepts query, category, manufacturer, equipment, evidence, supplier, availability, ordering and pagination parameters. The contact endpoint accepts the topics general, catalog data, procurement, supplier, accessibility and security.
04 · Model
Data responsibilities stay separate
CatalogPart
PartIdentifier
PartAttribute
EquipmentFitment
SupplierOffer
RFQ
Identity is not evidence
A part record may be correct while a fitment claim is unverified. A fitment may be plausible while a supplier offer is stale. The model preserves those independent states instead of flattening them into one trust score.05 · Reality
Implementation status
| Capability | Status | Boundary |
|---|---|---|
| Part discovery and filters | Implemented | Public Gritnox API and interface |
| Fitment evidence states | Implemented | Verified, claimed, unverified, rejected |
| Offer comparison | Implemented | Supplier-specific terms and freshness |
| Sourcing list | Implemented | Browser-local state |
| RFQ persistence | Implemented | Server-validated demo workflow |
| Contact intake | Implemented | Persisted demo inquiry and reference |
| Authentication and recovery | Implemented | HttpOnly session, CSRF, verification and revocation |
| Role-based demo workspace | Implemented | Fixed buyer, seller and administrator fixtures behind an opt-in demo endpoint |
| Multi-factor authentication | Not implemented | No TOTP, WebAuthn or recovery-code flow |
| Role dashboards | Implemented | Buyer, seller and administrator aggregates from persisted records |
| Authorization and store release | Implemented | Server-enforced roles and administrator-controlled activation |
| Checkout and orders | Implemented | Server-priced checkout, Stripe validation and scoped fulfilment |
| Supplier outreach | Not implemented | No supplier is contacted |
| Live inventory and pricing | Not implemented | All catalog data is illustrative |
06 · Checks
Validation is not implied by a successful render
- TypeScript and production-build checks validate the frontend route graph and component types.
- Django system checks validate project configuration without proving database migrations are applied.
- Database-backed tests require a reachable MongoDB instance and must be run against the configured environment.
- The scoped public-surface lint command and Jest suite pass independently of the production build. The full-repository lint backlog remains a documented cleanup gate.
- RFQ, contact and dashboard flows should be exercised end to end before any operational deployment.
Production gate
A production operator must complete migrations, database-backed tests, full-repository lint cleanup, independent security and accessibility review, secret rotation, hosting configuration and live workflow validation. The application is a working product concept, not a certified live procurement service.07 · Operations
Operational notes
- Set NEXT_PUBLIC_API_URL and NEXT_PUBLIC_SITE_URL for the deployment environment.
- Configure a reachable MongoDB URL, replace demo secrets and restrict allowed hosts.
- Run migrations and the idempotent seed command only in the intended environment.
- Review rate-limit storage and proxy headers before exposing public intake endpoints.
- Enable demo mode only on an isolated database and disable it before production use.
- Replace demo supplier data with authorized records before any real catalog use.