Technical & IT
Architecture, data model, APIs, deployment, and security reference for Project ROUNDTABLE
This section is the implementation reference for Project ROUNDTABLE. It describes how the application is built rather than how to use it. If you are looking for click-by-click instructions, read the user guide instead.
The /portal experience is for industry organizations. The /gov experience is for authenticated government personnel. The database, API routes, and src/lib services sit behind both; the architecture page explains how those pieces connect.
Where to start
New developer
Architect
Data engineer
API consumer
Security reviewer
Operator / IT
How the pieces fit together
Submission matching defaults to deterministic tag overlap; deployments opt in to Bedrock embedding scoring by setting MATCHING_SCORER=bedrock.
Industry users can edit their own profile and submissions; they cannot browse internal dialogue notes or export the enterprise dataset. Government users read and coordinate the ledger according to role and command scope. GOV_ADMIN and GOV_SYSTEM_ADMIN have enterprise visibility; only GOV_SYSTEM_ADMIN reorganizes the command tree.
Vocabulary that affects behavior
| Term | Meaning in this project |
|---|---|
| DoN | Department of the Navy. |
| CSO | Commercial Solutions Opening, the solicitation mechanism named by the pilot context. |
| NIWC | Naval Information Warfare Center. NIWC Pacific is the pilot context used in this repository. |
| SYSCOM | Systems Command, a major Navy organization such as NAVSEA or NAVWAR. |
| PEO | Program Executive Office, an acquisition organization responsible for a capability or portfolio. |
| POC | Point of contact, the person who receives or manages a technical area. |
| PAE | Portfolio Acquisition Executive structure represented by PortfolioNode records and routing tags. |
| Command | A government organizational unit with an optional parent and children; determines scope for many government users. |
| Organization | An industry participant such as a company, academic lab, FFRDC, or UARC; determines scope for industry users. |
| Submission | An industry-provided capability record and optional private file. |
| Engagement | A government ledger record of an interaction with an organization. |
| Tech tag | Lowercase comma-separated vocabulary used by matching and notification filters. |
| Portfolio node | The destination used by matching. |
| Audit log | Append-style record of security, authorization, and administrative events. |
| Export role | An enterprise capability, intentionally narrower than ordinary government read access. |
What is intentionally not implemented yet
The current implementation uses credentials-based NextAuth. CAC (Common Access Card), FlankSpeed identity federation, and Impact Level 5 (IL5) hosting hardening are future backfills. Treat these identity and hosting statements as roadmap boundaries, not current features.
Source-of-truth rule
This documentation is derived from prisma/schema.prisma, prisma/seed.ts, route handlers under src/app/api, shared services under src/lib, README.md, ARCHITECTURE.md, and deployment runbooks. When a marketing phrase and a route behavior differ, the route and schema define what the application actually does.
Suggested reading order
- Getting started — run the application and load seed data.
- Authentication and roles — read before testing any government page.
- Data model — commands, organizations, submissions, engagements.
- Industry portal or government ledger — surface-specific implementation.
- Matching and notifications — routing side effects.
- API reference — integrating or debugging a request.
- Deployment and security — before sharing an environment.
Where to look when something is wrong
| Symptom | Start with |
|---|---|
| Cannot sign in | Authentication and src/lib/auth.ts. |
| Portal page loads but submit fails | Portal API, S3 settings, and server logs. |
| Submission exists but no alert appears | Matching, InterestProfile, and notification settings. |
| Government user sees too much or too little | Scoping examples and command-hierarchy.ts. |
| Export is forbidden | Export API; only enterprise admin roles pass. |
| Docs page does not build | Check MDX syntax and run pnpm build in this repository. |
End users hitting problems in the browser should use the plain-language troubleshooting page instead.